mcstatusgo

package module
v2.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 11, 2022 License: MIT Imports: 11 Imported by: 2

README

mcstatusgo

mcstatusgo is a pure Go Minecraft service status checker for Java Edition Minecraft servers.

mcstatusgo supports requesting information through six protocols: status, legacy status, beta status, ping, basic query, and full query.

status, ping, basic query, and full query are the most up-to-date protocols.

legacy status and beta status are older implementations of status used in older versions of Minecraft.

Usage

Current Protocols
package main

import (
	"fmt"
	"time"

	"github.com/millkhan/mcstatusgo/v2"
)

func main() {
	// Experiment with both the initialTimeout and ioTimeout values to see what works best.
	initialTimeout := time.Second * 10
	ioTimeout := time.Second * 5

	// https://wiki.vg/Server_List_Ping
	status, err := mcstatusgo.Status("mc.piglin.org", 25565, initialTimeout, ioTimeout)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Max player count: %d\n", status.Players.Max)

	// https://wiki.vg/Server_List_Ping#Ping
	ping, err := mcstatusgo.Ping("mc.piglin.org", 25565, initialTimeout, ioTimeout)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Server latency: %s\n", ping)

	// https://wiki.vg/Query#Basic_stat
	basicQuery, err := mcstatusgo.BasicQuery("mc.piglin.org", 25565, initialTimeout, ioTimeout)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Map name: %s\n", basicQuery.MapName)

	// https://wiki.vg/Query#Full_stat
	fullQuery, err := mcstatusgo.FullQuery("mc.piglin.org", 25565, initialTimeout, ioTimeout)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Server version: %s\n", fullQuery.Version.Name)
}
Older Protocols
package main

import (
	"fmt"
	"time"

	"github.com/millkhan/mcstatusgo/v2"
)

func main() {
	// Experiment with both the initialTimeout and ioTimeout values to see what works best.
	initialTimeout := time.Second * 10
	ioTimeout := time.Second * 5

	// https://wiki.vg/Server_List_Ping#1.6
	statusLegacy, err := mcstatusgo.StatusLegacy("us.mineplex.com", 25565, initialTimeout, ioTimeout)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Max player count: %d\n", statusLegacy.Players.Max)

	// https://wiki.vg/Server_List_Ping#Beta_1.8_to_1.3
	statusBeta, err := mcstatusgo.StatusBeta("us.mineplex.com", 25565, initialTimeout, ioTimeout)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Online player count: %d\n", statusBeta.Players.Online)
}

Documentation

https://pkg.go.dev/github.com/millkhan/mcstatusgo/v2

Installation

mcstatusgo can be installed easily using the following command:

go get github.com/millkhan/mcstatusgo/v2

License

mcstatusgo is licensed under the MIT License. Check LICENSE for more information.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrShortQueryResponse is returned when the received response is too small to contain valid data.
	ErrShortQueryResponse error = errors.New("invalid query response: response is too small to contain valid data")
	// ErrShortChallengeToken is returned when the received challenge token is too small to be valid.
	ErrShortChallengeToken error = errors.New("invalid query response: challenge token is too small to contain valid data")
	// ErrAbsentChallengeTokenNullTerminator is returned when the challenge token doesn't contain a null-terminator at the end.
	ErrAbsentChallengeTokenNullTerminator = errors.New("invalid query response: challenge token doesn't contain a null-terminator")
	// ErrAbsentPlayerToken is returned when the player token used to split the full query response into two parts for parsing isn't present.
	ErrAbsentPlayerToken error = errors.New("invalid query response: player token not in response")
)

Errors.

View Source 
var (
	// ErrShortStatusResponse is returned when the received response is too small to contain valid data.
	ErrShortStatusResponse error = errors.New("invalid status response: response is too small to contain valid data")
	// ErrInvalidSizeInfo is returned when the information containing the JSON length does not match the actual JSON length.
	ErrInvalidSizeInfo error = errors.New("invalid status response: JSON size information is invalid")
	// ErrLargeVarInt is returned when a varint sent by the server is above the 5 bytes size limit.
	ErrLargeVarInt error = errors.New("invalid status response: varint sent by server exceeds size limit")
	// ErrInvalidPong is returned when the pong response received from the server does not match the ping packet sent to it.
	ErrInvalidPong error = errors.New("invalid status response: pong sent by server does not match ping packet")
)

Errors.

View Source 
var (
	// ErrShortStatusLegacyResponse is returned when the received response is too small to contain valid data.
	ErrShortStatusLegacyResponse error = errors.New("invalid status legacy response: response is too small to contain valid data")
	// ErrStatusLegacyMissingInformation is returned when the received response doesn't contain all 5 expected values.
	ErrStatusLegacyMissingInformation error = errors.New("invalid status legacy response: response doesn't contain all 5 expected values")
)

Errors.

View Source 
var (
	// ErrStatusBetaMissingInformation is returned when the received response doesn't contain all 3 expected values.
	ErrStatusBetaMissingInformation error = errors.New("invalid status beta response: response doesn't contain all 3 expected values")
)

Errors.

Functions

func Ping 

func Ping(server string, port uint16, initialConnectionTimeout time.Duration, ioTimeout time.Duration) (time.Duration, error)

Ping serves as a convenience wrapper over Status to retrieve the server latency.

Retrieving the latency from a StatusResponse provides the same function. https://wiki.vg/Server_List_Ping#Ping

Types

type BasicQueryResponse 

type BasicQueryResponse struct {
	// IP contains the server's IP.
	IP string

	// Port contains the server's port used for communication.
	Port uint16

	// Latency contains the duration of time waited for the basic query response.
	Latency time.Duration

	// Description contains the MOTD of the server.
	Description string

	// Gametype contains a string which is usually 'SMP'.
	GameType string

	// MapName contains the name of the map running on the server.
	MapName string

	Players struct {
		// Max contains the maximum number of players the server supports.
		Max int

		// Online contains the current number of players on the server.
		Online int
	}
}

BasicQueryResponse contains the information from the basic query request. https://wiki.vg/Query#Response_2

func BasicQuery 

func BasicQuery(server string, port uint16, initialConnectionTimeout time.Duration, ioTimeout time.Duration) (BasicQueryResponse, error)

BasicQuery requests basic server information from a Minecraft server.

The Minecraft server must have the "enable-query" property set to true.

If a valid response is received, a BasicQueryResponse is returned. https://wiki.vg/Query#Basic_stat

type ErrMissingInformation 

type ErrMissingInformation struct {
	// "status" or "query".
	Protocol string
	// The name of the value that was missing from the response.
	MissingValue string
}

ErrMissingInformation is returned when expected values are not receieved.

func (ErrMissingInformation) Error 

func (e ErrMissingInformation) Error() string

type FullQueryResponse 

type FullQueryResponse struct {
	// IP contains the server's IP.
	IP string

	// Port contains the server's port used for communication.
	Port uint16

	// Latency contains the duration of time waited for the full query response.
	Latency time.Duration

	// Description contains the MOTD of the server.
	Description string

	// Gametype contains a string which is usually 'SMP'.
	GameType string

	// GameID contains a string which is usually 'MINECRAFT'.
	GameID string

	// MapName contains the name of the map running on the server.
	MapName string

	Version struct {
		// Name contains the version of Minecraft running on the server.
		Name string
	}

	Players struct {
		// Max contains the maximum number of players the server supports.
		Max int

		// Online contains the current number of players on the server.
		Online int

		// PlayerList contains the usernames of the players currently on the server.
		PlayerList []string
	}

	ModInfo struct {
		// Type contains the server mod running on the server.
		Type string

		// ModList contains the plugins with their versions running on the server.
		ModList []map[string]string
	}
}

FullQueryResponse contains the information from the full query request. https://wiki.vg/Query#Response_3

func FullQuery 

func FullQuery(server string, port uint16, initialConnectionTimeout time.Duration, ioTimeout time.Duration) (FullQueryResponse, error)

FullQuery requests detailed server information from a Minecraft server.

The Minecraft server must have the "enable-query" property set to true.

If a valid response is received, a FullQueryResponse is returned. https://wiki.vg/Query#Full_stat

type StatusBetaResponse added in v2.2.0 

type StatusBetaResponse struct {
	// IP contains the server's IP.
	IP string

	// Port contains the server's port used for communication.
	Port uint16

	// Latency contains the duration of time waited for the response.
	Latency time.Duration

	// Description contains the MOTD of the server.
	Description string

	Players struct {
		// Max contains the maximum number of players the server supports.
		Max int

		// Online contains the current number of players on the server.
		Online int
	}
}

StatusBetaResponse contains the information from the beta status request.

func StatusBeta added in v2.2.0 

func StatusBeta(server string, port uint16, initialConnectionTimeout time.Duration, ioTimeout time.Duration) (StatusBetaResponse, error)

StatusBeta requests basic server information from a Minecraft server using the beta (oldest version) implementation of Status.

The Minecraft server must have SLP enabled.

If a valid response is received, a StatusBetaResponse is returned. https://wiki.vg/Server_List_Ping#Beta_1.8_to_1.3

type StatusLegacyResponse added in v2.1.0 

type StatusLegacyResponse struct {
	// IP contains the server's IP.
	IP string

	// Port contains the server's port used for communication.
	Port uint16

	// Latency contains the duration of time waited for the response.
	Latency time.Duration

	// Description contains the MOTD of the server.
	Description string

	Version struct {
		// Name contains the version of Minecraft running on the server.
		Name string

		// Protocol contains the protocol version used in the request or that should be used when connecting to the server.
		Protocol int
	}

	Players struct {
		// Max contains the maximum number of players the server supports.
		Max int

		// Online contains the current number of players on the server.
		Online int
	}
}

StatusLegacyResponse contains the information from the legacy status request. https://wiki.vg/Server_List_Ping#Server_to_client

func StatusLegacy added in v2.1.0 

func StatusLegacy(server string, port uint16, initialConnectionTimeout time.Duration, ioTimeout time.Duration) (StatusLegacyResponse, error)

StatusLegacy requests basic server information from a Minecraft server using the older legacy implementation of Status.

The Minecraft server must have SLP enabled.

If a valid response is received, a StatusLegacyResponse is returned. https://wiki.vg/Server_List_Ping#1.6

type StatusResponse 

type StatusResponse struct {
	// IP contains the server's IP.
	IP string

	// Port contains the server's port used for communication.
	Port uint16

	// Latency contains the duration of time waited for the pong.
	Latency time.Duration

	// Description contains a pretty-print JSON string of the server description.
	Description string `json:"-"`

	// Favicon contains the base64 encoded PNG image of the server that appears in the server list.
	Favicon string

	Version struct {
		// Name contains the version of Minecraft running on the server.
		Name string

		// Protocol contains the protocol version used in the request or that should be used when connecting to the server.
		Protocol int
	}

	Players struct {
		// Max contains the maximum number of players the server supports.
		Max int

		// Online contains the current number of players on the server.
		Online int

		// Sample contains a random sample of players with their username and uuid currently on the server.
		Sample []map[string]string
	}

	ModInfo struct {
		// Type contains the server mod running on the server.
		Type string

		// ModList contains the plugins with their versions running on the server.
		ModList []map[string]string
	}
}

StatusResponse contains the information from the status request. https://wiki.vg/Server_List_Ping#Response

func Status 

func Status(server string, port uint16, initialConnectionTimeout time.Duration, ioTimeout time.Duration) (StatusResponse, error)

Status requests basic server information from a Minecraft server.

The Minecraft server must have SLP enabled.

If a valid response is received, a StatusResponse is returned. https://wiki.vg/Server_List_Ping

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.