Restructure project

Author: TrixterTheTux

README.md

@@ -1,8 +1,31 @@
 # gamequery
 A Golang package for querying game servers  
 
-**This package is WIP and should not be used in production.**
-
 ## Supported protocols:
 Source Query  
-Minecraft TCP & UDP  
+Minecraft TCP & UDP  
+
+## Sample code:
+```go
+package main
+
+import (
+	"fmt"
+	"github.com/wisp-gg/gamequery"
+	"github.com/wisp-gg/gamequery/api"
+)
+
+func main() {
+	res, protocol, err := gamequery.Detect(api.Request{
+		IP: "127.0.0.1",
+		Port: 27015,
+	})
+	if err != nil {
+		fmt.Printf("failed to query: %s", err)
+		return
+	}
+
+	fmt.Printf("Detected the protocol: %s\n", protocol)
+	fmt.Printf("%+v\n", res)
+}
+```

api/structs.go

@@ -0,0 +1,18 @@
+package api
+
+import "time"
+
+// Representation of a query request for a specific game server.
+type Request struct {
+	Game    string         // The game protocol to use, can be left out for the `Detect` function.
+	IP      string         // The game server's query IP
+	Port    uint16         // The game server's query port
+	Timeout *time.Duration // Timeout for a single send/receive operation in the game's protocol.
+}
+
+// Representation of a query result for a specific game server.
+type Response struct {
+	// TODO: Decide the structure of this
+
+	Raw interface{} // Contains the original, raw response received from the game's protocol.
+}

gamequery.go

@@ -2,28 +2,22 @@ package gamequery
 
 import (
 	"errors"
-	"github.com/wisp-gg/gamequery/protocols"
+	"github.com/wisp-gg/gamequery/api"
+	"github.com/wisp-gg/gamequery/internal"
+	"github.com/wisp-gg/gamequery/internal/protocols"
 	"sort"
 	"sync"
 	"time"
 )
 
-// Representation of a query request for a specific game server.
-type Request struct {
-	Game    string         // The game protocol to use, can be left out for the `Detect` function.
-	IP      string         // The game server's query IP
-	Port    uint16         // The game server's query port
-	Timeout *time.Duration // Timeout for a single send/receive operation in the game's protocol.
-}
-
-var queryProtocols = []protocols.Protocol{
+var queryProtocols = []internal.Protocol{
 	protocols.SourceQuery{},
 	protocols.MinecraftUDP{},
 	protocols.MinecraftTCP{},
 }
 
-func findProtocols(name string) []protocols.Protocol {
-	found := make([]protocols.Protocol, 0)
+func findProtocols(name string) []internal.Protocol {
+	found := make([]internal.Protocol, 0)
 	for _, protocol := range queryProtocols {
 		if protocol.Name() == name {
 			found = append(found, protocol)
@@ -43,35 +37,35 @@ type queryResult struct {
 	Name     string
 	Priority uint16
 	Err      error
-	Response protocols.Response
+	Response api.Response
 }
 
 // Query the game server by detecting the protocol (trying all available protocols).
 // This usually should be used as the initial query function and then use `Query` function
 // with the returned protocol if the query succeeds. Otherwise each function call will take always
 // <req.Timeout> duration even if the response was received earlier from one of the protocols.
-func Detect(req Request) (protocols.Response, string, error) {
+func Detect(req api.Request) (api.Response, string, error) {
 	return query(req, queryProtocols)
 }
 
 // Query the game server using the protocol provided in req.Game.
-func Query(req Request) (protocols.Response, error) {
+func Query(req api.Request) (api.Response, error) {
 	chosenProtocols := findProtocols(req.Game)
 	if len(chosenProtocols) < 1 {
-		return protocols.Response{}, errors.New("could not find protocols for the game")
+		return api.Response{}, errors.New("could not find protocols for the game")
 	}
 
 	response, _, err := query(req, chosenProtocols)
 	return response, err
 }
 
-func query(req Request, chosenProtocols []protocols.Protocol) (protocols.Response, string, error) {
+func query(req api.Request, chosenProtocols []internal.Protocol) (api.Response, string, error) {
 	var wg sync.WaitGroup
 	wg.Add(len(chosenProtocols))
 
 	queryResults := make([]queryResult, len(chosenProtocols))
 	for index, queryProtocol := range chosenProtocols {
-		go func(queryProtocol protocols.Protocol, index int) {
+		go func(queryProtocol internal.Protocol, index int) {
 			defer wg.Done()
 
 			var port = queryProtocol.DefaultPort()
@@ -84,12 +78,12 @@ func query(req Request, chosenProtocols []protocols.Protocol) (protocols.Respons
 				timeout = *req.Timeout
 			}
 
-			networkHelper := protocols.NetworkHelper{}
+			networkHelper := internal.NetworkHelper{}
 			if err := networkHelper.Initialize(queryProtocol.Network(), req.IP, port, timeout); err != nil {
 				queryResults[index] = queryResult{
 					Priority: queryProtocol.Priority(),
 					Err:      err,
-					Response: protocols.Response{},
+					Response: api.Response{},
 				}
 				return
 			}
@@ -100,7 +94,7 @@ func query(req Request, chosenProtocols []protocols.Protocol) (protocols.Respons
 				queryResults[index] = queryResult{
 					Priority: queryProtocol.Priority(),
 					Err:      err,
-					Response: protocols.Response{},
+					Response: api.Response{},
 				}
 				return
 			}
@@ -130,5 +124,5 @@ func query(req Request, chosenProtocols []protocols.Protocol) (protocols.Respons
 		}
 	}
 
-	return protocols.Response{}, "", firstError
+	return api.Response{}, "", firstError
 }

protocols/network_helper.go renamed to internal/network_helper.go

@@ -1,4 +1,4 @@
-package protocols
+package internal
 
 import (
 	"fmt"

protocols/packet.go renamed to internal/packet.go

@@ -1,4 +1,4 @@
-package protocols
+package internal
 
 import (
 	"encoding/binary"

internal/protocol.go

@@ -0,0 +1,15 @@
+package internal
+
+import (
+	"github.com/wisp-gg/gamequery/api"
+)
+
+type Protocol interface {
+	Name() string
+	Aliases() []string
+	DefaultPort() uint16
+	Priority() uint16
+	Network() string
+
+	Execute(helper NetworkHelper) (api.Response, error)
+}

protocols/minecraft_tcp.go renamed to internal/protocols/minecraft_tcp.go

@@ -5,6 +5,8 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"github.com/wisp-gg/gamequery/api"
+	"github.com/wisp-gg/gamequery/internal"
 )
 
 type MinecraftTCP struct{}
@@ -58,11 +60,11 @@ func (mc MinecraftTCP) Network() string {
 	return "tcp"
 }
 
-func buildMCPacket(bulkData ...interface{}) *Packet {
-	packet := Packet{}
+func buildMCPacket(bulkData ...interface{}) *internal.Packet {
+	packet := internal.Packet{}
 	packet.SetOrder(binary.BigEndian)
 
-	tmpPacket := Packet{}
+	tmpPacket := internal.Packet{}
 	tmpPacket.SetOrder(binary.BigEndian)
 	for _, data := range bulkData {
 		switch val := data.(type) {
@@ -86,26 +88,26 @@ func buildMCPacket(bulkData ...interface{}) *Packet {
 	return &packet
 }
 
-func (mc MinecraftTCP) Execute(helper NetworkHelper) (Response, error) {
+func (mc MinecraftTCP) Execute(helper internal.NetworkHelper) (api.Response, error) {
 	err := helper.Send(buildMCPacket([]byte{0x00, 0x00}, helper.GetIP(), helper.GetPort(), 0x01).GetBuffer())
 	if err != nil {
-		return Response{}, err
+		return api.Response{}, err
 	}
 
 	err = helper.Send(buildMCPacket(0x00).GetBuffer())
 	if err != nil {
-		return Response{}, err
+		return api.Response{}, err
 	}
 
 	responsePacket, err := helper.Receive()
 	if err != nil {
-		return Response{}, err
+		return api.Response{}, err
 	}
 
 	packetLength := responsePacket.ReadVarint()
 	packetId := responsePacket.ReadVarint()
 	if packetId != 0 {
-		return Response{}, errors.New("received something else than a status response")
+		return api.Response{}, errors.New("received something else than a status response")
 	}
 
 	if packetId > packetLength {
@@ -119,14 +121,14 @@ func (mc MinecraftTCP) Execute(helper NetworkHelper) (Response, error) {
 	raw := MinecraftTCPRaw{}
 	err = json.Unmarshal([]byte(jsonBody), &raw)
 	if err != nil {
-		return Response{}, err
+		return api.Response{}, err
 	}
 
 	if responsePacket.IsInvalid() {
-		return Response{}, errors.New("received packet is invalid")
+		return api.Response{}, errors.New("received packet is invalid")
 	}
 
-	return Response{
+	return api.Response{
 		Raw: raw,
 	}, nil
 }

protocols/minecraft_udp.go renamed to internal/protocols/minecraft_udp.go

@@ -4,6 +4,8 @@ import (
 	"bytes"
 	"encoding/binary"
 	"errors"
+	"github.com/wisp-gg/gamequery/api"
+	"github.com/wisp-gg/gamequery/internal"
 	"math/rand"
 	"strconv"
 	"time"
@@ -68,36 +70,36 @@ func parseChallengeToken(challengeToken string) ([]byte, error) {
 	return buf.Bytes()[buf.Len()-4:], nil
 }
 
-func (mc MinecraftUDP) Execute(helper NetworkHelper) (Response, error) {
+func (mc MinecraftUDP) Execute(helper internal.NetworkHelper) (api.Response, error) {
 	sessionId := generateSessionID()
 
-	packet := Packet{}
+	packet := internal.Packet{}
 	packet.SetOrder(binary.BigEndian)
 	packet.WriteRaw(0xFE, 0xFD, 0x09)
 	packet.WriteInt32(sessionId)
 
 	err := helper.Send(packet.GetBuffer())
 	if err != nil {
-		return Response{}, err
+		return api.Response{}, err
 	}
 
 	handshakePacket, err := helper.Receive()
 	if err != nil {
-		return Response{}, err
+		return api.Response{}, err
 	}
 
 	handshakePacket.SetOrder(binary.BigEndian)
 	if handshakePacket.ReadUint8() != 0x09 {
-		return Response{}, errors.New("sent a handshake, but didn't receive handshake response back")
+		return api.Response{}, errors.New("sent a handshake, but didn't receive handshake response back")
 	}
 
 	if handshakePacket.ReadInt32() != sessionId {
-		return Response{}, errors.New("received handshake for wrong session id")
+		return api.Response{}, errors.New("received handshake for wrong session id")
 	}
 
 	challengeToken, err := parseChallengeToken(handshakePacket.ReadString())
 	if err != nil {
-		return Response{}, err
+		return api.Response{}, err
 	}
 
 	packet.Clear()
@@ -108,21 +110,21 @@ func (mc MinecraftUDP) Execute(helper NetworkHelper) (Response, error) {
 
 	err = helper.Send(packet.GetBuffer())
 	if err != nil {
-		return Response{}, err
+		return api.Response{}, err
 	}
 
 	responsePacket, err := helper.Receive()
 	if err != nil {
-		return Response{}, err
+		return api.Response{}, err
 	}
 
 	responsePacket.SetOrder(binary.BigEndian)
 	if responsePacket.ReadUint8() != 0x00 {
-		return Response{}, errors.New("sent a full stat request, but didn't receive stat response back")
+		return api.Response{}, errors.New("sent a full stat request, but didn't receive stat response back")
 	}
 
 	if responsePacket.ReadInt32() != sessionId {
-		return Response{}, errors.New("received handshake for wrong session id")
+		return api.Response{}, errors.New("received handshake for wrong session id")
 	}
 
 	responsePacket.Forward(11)
@@ -175,10 +177,10 @@ func (mc MinecraftUDP) Execute(helper NetworkHelper) (Response, error) {
 	}
 
 	if responsePacket.IsInvalid() {
-		return Response{}, errors.New("received packet is invalid")
+		return api.Response{}, errors.New("received packet is invalid")
 	}
 
-	return Response{
+	return api.Response{
 		Raw: raw,
 	}, nil
 }