minestat 2.0.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c241df5d1adebf63bf3fa8ff85a4066cf788b64ac160afddf99906f6d0ea1a3
-  data.tar.gz: c257c9b9640bb4bf961bdc80dfbebbcad829cfe5a56f90951bc724859ab389c7
+  metadata.gz: 289592d2813eb1246b9a3033ce10a219513bf0c9cb792951051bdf6f97b20598
+  data.tar.gz: beee739e9c19250fb6663e9561e065dfbcbae817442afe07ca3a21911e5f975a
 SHA512:
-  metadata.gz: afb6c96adcac8c9bcea0bb88e1466ef9354d116345707c1f9fa901322996d412c8244a59c5facd724909d7f16375f5c3dcc098f40aef484ca8a9d18dff4936c4
-  data.tar.gz: c08c4a7f1099ed57094bedf7c4f3eed374eff7fa824be55a1962b3fa3831f6f2f088284ee0b58acc09c7285b33fea8892ed8abfbe5b757264876497c3ff637d0
+  metadata.gz: ad094493fac2c5b788c7ed86bdcc1e5296715d410cfe435491101fa56aae2bda6cd81644a88ce8caf183e6ae13072e559a073a4a4b42f9a51b0dfe261a46b378
+  data.tar.gz: a757852cab9404fe9937a9a4f9fb7bac2effccd3317173d2abf0bc200a87dea5a6576e382c878be9d15f31b2489298197fafa6f5c1b4eaa1aff75d90f6ab6c16

data/lib/minestat.rb

@@ -1,5 +1,5 @@
 # minestat.rb - A Minecraft server status checker
-# Copyright (C) 2014-2021 Lloyd Dilley
+# Copyright (C) 2014-2022 Lloyd Dilley
 # http://www.dilley.me/
 #
 # This program is free software; you can redistribute it and/or modify
@@ -20,43 +20,81 @@ require 'json'
 require 'socket'
 require 'timeout'
 
+##
+# Provides a ruby interface for polling Minecraft server status.
 class MineStat
-  VERSION = "2.0.0"    # MineStat version
-  NUM_FIELDS = 6       # number of values expected from server
-  NUM_FIELDS_BETA = 3  # number of values expected from a 1.8b/1.3 server
-  MAX_VARINT_SIZE = 5  # maximum number of bytes a varint can be
-  DEFAULT_PORT = 25565 # default TCP port
-  DEFAULT_TIMEOUT = 5  # default TCP timeout in seconds
+  # MineStat version
+  VERSION = "2.2.0"
+  # 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
+  # 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
+  BEDROCK_PACKET_OFFSET = 35
 
+  ##
+  # 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
 
+  ##
+  # 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
+    # Bedrock/Pocket Edition
+    BEDROCK = 4
   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
-    @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
+    @address = address    # address of server
+    @port = port          # TCP/UDP port of server
+    @online               # online or offline?
+    @version              # server version
+    @mode = "Unspecified" # game mode (Bedrock/Pocket Edition only)
+    @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/UDP timeout
+    @server               # server socket
+    @request_type         # Protocol version
 
     case request_type
       when Request::BETA
@@ -67,13 +105,14 @@ class MineStat
         retval = extended_legacy_request()
       when Request::JSON
         retval = json_request()
+      when Request::BEDROCK
+        retval = bedrock_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
+        # Attempt various SLP ping requests in a particular order. If 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
@@ -81,22 +120,53 @@ class MineStat
           retval = beta_request()
         end
         # SLP 1.6
-        unless retval == Retval::SUCCESS || retval == Retval::CONNFAIL
+        unless retval == Retval::CONNFAIL
           retval = extended_legacy_request()
         end
         # SLP 1.7
-        unless retval == Retval::SUCCESS || retval == Retval::CONNFAIL
+        unless retval == Retval::CONNFAIL
           retval = json_request()
         end
+        # Bedrock
+        unless retval == Retval::CONNFAIL
+          retval = bedrock_request()
+        end
     end
     @online = false unless retval == Retval::SUCCESS
   end
 
-  # Connects to remote server
+  # Strips message of the day formatting characters
+  def strip_motd()
+    unless @motd['text'] == nil
+      @stripped_motd = @motd['text']
+    else
+      @stripped_motd = @motd
+    end
+    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.force_encoding('UTF-8')
+    @stripped_motd = @stripped_motd.gsub(/§./, "")
+  end
+
+  ##
+  # Establishes a connection to the Minecraft server
   def connect()
     begin
-      start_time = Time.now
-      @server = TCPSocket.new(@address, @port)
+      if @request_type == Request::BEDROCK || @request_type == "Bedrock/Pocket Edition"
+        @port = DEFAULT_BEDROCK_PORT if @port == DEFAULT_PORT && @request_type == Request::NONE
+        start_time = Time.now
+        @server = UDPSocket.new
+        @server.connect(@address, @port)
+      else
+        start_time = Time.now
+        @server = TCPSocket.new(@address, @port)
+      end
       @latency = ((Time.now - start_time) * 1000).round
     rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH
       return Retval::CONNFAIL
@@ -111,16 +181,28 @@ class MineStat
   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
+      if @request_type == "Bedrock/Pocket Edition"
+        if @server.recv(1, Socket::MSG_PEEK).unpack('C').first == 0x1C # unconnected pong packet
+          server_id_len = @server.recv(BEDROCK_PACKET_OFFSET, Socket::MSG_PEEK)[-2..-1].unpack('n').first
+          data = @server.recv(BEDROCK_PACKET_OFFSET + server_id_len)[BEDROCK_PACKET_OFFSET..-1]
+          @server.close
+        else
+          @server.close
+          return Retval::UNKNOWN
+        end
+      else # SLP
+        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
-    rescue => exception
-      $stderr.puts exception
+    rescue
+    #rescue => exception
+      #$stderr.puts exception
       return Retval::UNKNOWN
     end
 
@@ -133,18 +215,33 @@ class MineStat
       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
+    elsif @request_type == "Bedrock/Pocket Edition"
+      if server_info != nil
+        @protocol = server_info[2].to_i
+        @version = "#{server_info[3]} #{server_info[7]} (#{server_info[0]})"
+        @mode = server_info[8]
+        @motd = server_info[1]
+        strip_motd
+        @current_players = server_info[4].to_i
+        @max_players = server_info[5].to_i
+        @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
         @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
@@ -155,14 +252,17 @@ class MineStat
     return Retval::SUCCESS
   end
 
-  # 1.8b/1.3
+  ##
   # 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
+  # The 3 fields, in order, are:
+  # * message of the day
+  # * current players
+  # * max players
   def beta_request()
     retval = nil
     begin
@@ -183,7 +283,7 @@ class MineStat
     return retval
   end
 
-  # 1.4/1.5
+  ##
   # 1.4 and 1.5 servers communicate as follows for a ping request:
   # 1. Client sends:
   #   1a. \xFE (server list ping)
@@ -192,8 +292,14 @@ 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_request()
@@ -216,7 +322,7 @@ class MineStat
     return retval
   end
 
-  # 1.6
+  ##
   # 1.6 servers communicate as follows for a ping request:
   # 1. Client sends:
   #   1a. \xFE (server list ping)
@@ -233,8 +339,14 @@ 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 extended_legacy_request()
@@ -264,7 +376,7 @@ class MineStat
     return retval
   end
 
-  # 1.7
+  ##
   # 1.7 to current servers communicate as follows for a ping request:
   # 1. Client sends:
   #   1a. \x00 (handshake packet containing the fields specified below)
@@ -309,7 +421,8 @@ class MineStat
         @json_data = json_data
         @protocol = json_data['version']['protocol'].to_i
         @version = json_data['version']['name']
-        @motd = json_data['description']['text']
+        @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?
@@ -361,5 +474,100 @@ class MineStat
     return vint
   end
 
-  attr_reader :address, :port, :online, :version, :motd, :current_players, :max_players, :protocol, :json_data, :latency, :request_type
+  ##
+  # 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 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
+  def bedrock_request()
+    retval = nil
+    begin
+      Timeout::timeout(@timeout) do
+        @request_type = "Bedrock/Pocket Edition"
+        retval = connect()
+        return retval unless retval == Retval::SUCCESS
+        # Perform handshake and acquire data
+        payload = "\x01".force_encoding('ASCII-8BIT')                       # unconnected ping
+        payload += [Time.now.to_i].pack('L!<').force_encoding('ASCII-8BIT') # current time as a long
+        payload += "\x00\xFF\xFF\x00\xFE\xFE\xFE\xFE\xFD\xFD\xFD\xFD\x12\x34\x56\x78".force_encoding('ASCII-8BIT') # magic number
+        payload += [2].pack('L!<').force_encoding('ASCII-8BIT')             # client GUID as a long
+        @server.write(payload)
+        @server.flush
+        retval = parse_data("\x3B") # semicolon
+      end
+    rescue Timeout::Error
+      return Retval::TIMEOUT
+    rescue => exception
+      $stderr.puts exception
+      return Retval::UNKNOWN
+    end
+    return retval
+  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 game mode (Bedrock/Pocket Edition only)
+  attr_reader :mode
+
+  # 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,15 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: minestat
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Lloyd Dilley
-- Stepan Melnikov
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-03-03 00:00:00.000000000 Z
+date: 2022-05-01 00:00:00.000000000 Z
 dependencies: []
 description: MineStat polls Minecraft server data such as version, motd, current players,
   and max players.
@@ -24,7 +23,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 +38,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.3.7
+signing_key:
 specification_version: 4
 summary: Minecraft server status checker
 test_files: []