Implement Classic protocol support

Author: catfromplan9

common.go

@@ -978,3 +978,49 @@ func (app *App) BaseRelativePath(path_ string) (string, error) {
 	baseRelative := strings.TrimPrefix(path_, app.BasePath)
 	return strings.TrimSuffix(baseRelative, "/"), nil
 }
+
+// Remove servers who haven't pinged for a while from the LRU
+func (app *App) cleanupHeartbeatLRU() {
+	now := time.Now()
+	for {
+		heartbeatLruMutex.Lock()
+		back := heartbeatLruList.Back()
+		if back == nil {
+			heartbeatLruMutex.Unlock()
+			break
+		}
+		key := back.Value.(ServerKey)
+
+		heartbeatSaltMapMutex.RLock()
+		entry, ok := heartbeatSaltMap[key]
+		heartbeatSaltMapMutex.RUnlock()
+
+		if !ok {
+			heartbeatLruList.Remove(back)
+			heartbeatLruMutex.Unlock()
+			continue
+		}
+
+		if now.Sub(entry.Timestamp) > heartbeatLruTTL {
+			heartbeatSaltMapMutex.Lock()
+			delete(heartbeatSaltMap, key)
+			heartbeatSaltMapMutex.Unlock()
+			heartbeatLruList.Remove(back)
+			heartbeatLruMutex.Unlock()
+		} else {
+			heartbeatLruMutex.Unlock()
+			break
+		}
+	}
+}
+
+func (app *App) RunPeriodicTasks() {
+	go func() {
+		ticker := time.NewTicker(10 * time.Minute) // repeat every 10 minutes
+		defer ticker.Stop()
+
+		for range ticker.C {
+			app.cleanupHeartbeatLRU()
+		}
+	}()
+}

config.go

@@ -145,6 +145,7 @@ type BaseConfig struct {
 	MinPasswordLength          int
 	PlayerUUIDGeneration       string
 	PreMigrationBackups        bool
+	PublicIP                   string
 	RateLimit                  rateLimitConfig
 	RegistrationExistingPlayer registrationExistingPlayerConfig
 	RegistrationNewPlayer      registrationNewPlayerConfig
@@ -224,6 +225,7 @@ func DefaultRawConfig() RawConfig {
 			OfflineSkins:         true,
 			PlayerUUIDGeneration: "random",
 			PreMigrationBackups:  true,
+			PublicIP:             "",
 			RateLimit:            defaultRateLimitConfig,
 			RegistrationExistingPlayer: registrationExistingPlayerConfig{
 				Allow: false,

doc/configuration.md

@@ -129,3 +129,4 @@ Other available options:
 - `ValidPlayerNameRegex`: Regular expression (regex) that player names must match. Currently, Drasl usernames are validated using this regex too. Player names will be limited to a maximum of 16 characters no matter what. Mojang allows the characters `abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_`, and by default, Drasl follows suit. Minecraft servers may misbehave if additional characters are allowed. Change to `.+` if you want to allow any player name (that is 16 characters or shorter). String. Default value: `^[a-zA-Z0-9_]+$`.
 - `CORSAllowOrigins`: List of origins that may access Drasl API routes. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin. Necessary for allowing browsers to access the Drasl API. Set to `["*"]` to allow all origins. Array of strings. Example value: `["https://front-end.example.com"]`. Default value: `[]`.
 - `PlayerUUIDGeneration`: How to generate UUIDs for new players. Must be either `"random"` or `"offline"`. `"random"` generates a new random Version 4 UUID. `"offline"` means the player's UUID will be generated from the player's name using the same algorithm Minecraft uses to derive player UUIDs on `online-mode=false` servers. `PlayerUUIDGeneration = "offline"` is useful for migrating `online-mode=false` servers to Drasl since it lets player UUIDs (and thus inventories, permissions, etc.) remain the same when switching from `online-mode=false` to `online-mode=true`. Note: if a player's name is changed, their UUID will not change, even with `PlayerUUIDGeneration = "offline"`. String. Default value: `"random"`.
+- `PublicIP`: IPv4 address to assign to [Classic server protocol heartbeat requests](https://minecraft.wiki/w/Classic_server_protocol#Heartbeats) when the originating IP is loopback or within a private IP range. Useful when Drasl runs on the same system as the Minecraft server it communicates with, allowing the heartbeat to report an externally reachable address instead of a local one. If not set, Drasl automatically determines a suitable address from the system's network interfaces. This option can be set manually to resolve network detection or routing issues in certain environments. String. Default value: `""`.

main.go

@@ -363,13 +363,17 @@ func (app *App) MakeServer() *echo.Echo {
 	sessionJoinServer := SessionJoinServer(app)
 	sessionProfile := SessionProfile(app, false)
 	sessionBlockedServers := SessionBlockedServers(app)
+	sessionHeartbeat := SessionHeartbeat(app)
+	sessionGetMpPass := SessionGetMpPass(app)
 	for _, prefix := range []string{"", "/session", "/authlib-injector/sessionserver"} {
 		base.GET(prefix+"/session/minecraft/hasJoined", sessionHasJoined)
 		base.GET(prefix+"/game/checkserver.jsp", sessionCheckServer)
 		base.POST(prefix+"/session/minecraft/join", sessionJoin)
 		base.GET(prefix+"/game/joinserver.jsp", sessionJoinServer)
 		base.GET(prefix+"/session/minecraft/profile/:id", sessionProfile)
 		base.GET(prefix+"/blockedservers", sessionBlockedServers)
+		base.Any(prefix+"/heartbeat.jsp", sessionHeartbeat)
+		base.GET(prefix+"/getMpPass", sessionGetMpPass)
 	}
 
 	// Services
@@ -653,6 +657,8 @@ func (app *App) Run() {
 	for _, fallbackAPIServer := range PtrSlice(app.FallbackAPIServers) {
 		go app.PlayerNamesToIDsWorker(fallbackAPIServer)
 	}
+
+	app.RunPeriodicTasks()
 }
 
 func main() {

session.go

@@ -1,15 +1,22 @@
 package main
 
 import (
+	"container/list"
+	"crypto/md5"
+	"encoding/hex"
 	"errors"
 	"fmt"
 	"github.com/labstack/echo/v4"
 	"github.com/samber/mo"
 	"gorm.io/gorm"
 	"log"
+	"net"
 	"net/http"
 	"net/url"
+	"strconv"
 	"strings"
+	"sync"
+	"time"
 )
 
 type sessionJoinRequest struct {
@@ -18,6 +25,25 @@ type sessionJoinRequest struct {
 	ServerID        string `json:"serverId"`
 }
 
+type ServerKey struct {
+	IP   string
+	Port int
+}
+
+type heartbeatSaltEntry struct {
+	Salt      string
+	Timestamp time.Time
+	Elem      *list.Element
+}
+
+var (
+	heartbeatSaltMap      = make(map[ServerKey]heartbeatSaltEntry)
+	heartbeatSaltMapMutex sync.RWMutex
+	heartbeatLruList      = list.New()
+	heartbeatLruMutex     sync.Mutex
+	heartbeatLruTTL       = 5 * time.Minute // Server should send one every 45 seconds
+)
+
 // /session/minecraft/join
 // https://minecraft.wiki/w/Minecraft_Wiki:Projects/wiki.vg_merge/Protocol_Encryption#Client
 func SessionJoin(app *App) func(c echo.Context) error {
@@ -277,3 +303,137 @@ func SessionBlockedServers(app *App) func(c echo.Context) error {
 		return c.NoContent(http.StatusOK)
 	}
 }
+
+func (app *App) heartbeat(c *echo.Context, ip string, port int, salt string) error {
+	key := ServerKey{IP: ip, Port: port}
+	now := time.Now()
+
+	heartbeatSaltMapMutex.Lock()
+	entry, exists := heartbeatSaltMap[key]
+	if exists {
+		// Update value by overwriting the map entry
+		entry.Salt = salt
+		entry.Timestamp = now
+		heartbeatSaltMap[key] = entry
+	} else {
+		// New entry
+		entry = heartbeatSaltEntry{
+			Salt:      salt,
+			Timestamp: now,
+		}
+		heartbeatSaltMap[key] = entry
+	}
+
+	heartbeatSaltMapMutex.Unlock()
+
+	// Handle heartbeat LRU
+	heartbeatLruMutex.Lock()
+	if exists {
+		heartbeatLruList.MoveToFront(entry.Elem)
+	} else {
+		entry.Elem = heartbeatLruList.PushFront(key)
+		// Save back updated element
+		heartbeatSaltMapMutex.Lock()
+		heartbeatSaltMap[key] = entry
+		heartbeatSaltMapMutex.Unlock()
+	}
+	heartbeatLruMutex.Unlock()
+
+	return (*c).String(http.StatusOK, fmt.Sprintf("%s:%d", ip, port))
+}
+
+// /heartbeat.jsp
+// https://minecraft.wiki/w/Classic_server_protocol
+// https://www.grahamedgecombe.com/talks/minecraft.pdf
+func SessionHeartbeat(app *App) func(c echo.Context) error {
+	return func(c echo.Context) error {
+		ip := c.RealIP()
+		parsed := net.ParseIP(ip)
+
+		// Prefer PublicIP config over request IP on private/loopback address ranges
+		if parsed != nil && (parsed.IsLoopback() || parsed.IsPrivate()) && app.Config.PublicIP != "" {
+			ip = app.Config.PublicIP
+		}
+
+		// Require port
+		portStr := c.FormValue("port")
+		if portStr == "" {
+			portStr = c.QueryParam("port")
+		}
+		if portStr == "" {
+			return c.String(http.StatusBadRequest, "missing required query parameter: port")
+		}
+		port, err := strconv.Atoi(portStr)
+		if err != nil || port <= 0 || port > 65535 {
+			return c.String(http.StatusBadRequest, "invalid port value")
+		}
+
+		// Require salt
+		salt := c.FormValue("salt")
+		if salt == "" {
+			salt = c.QueryParam("salt")
+		}
+		if salt == "" {
+			salt = "missingno" // no salt here! are we speaking with c0.0.15a-c0.0.16a?
+		}
+
+		return app.heartbeat(&c, ip, port, salt)
+	}
+}
+
+func (app *App) getMpPass(c *echo.Context, playerName string, ip string, port int) error {
+	key := ServerKey{IP: ip, Port: port}
+
+	heartbeatSaltMapMutex.RLock()
+	entry, ok := heartbeatSaltMap[key]
+	heartbeatSaltMapMutex.RUnlock()
+
+	if !ok {
+		return (*c).NoContent(http.StatusNotFound)
+	}
+
+	hash := md5.Sum([]byte(entry.Salt + playerName))
+	return (*c).String(http.StatusOK, hex.EncodeToString(hash[:]))
+}
+
+func SessionGetMpPass(app *App) func(c echo.Context) error {
+	return withBearerAuthentication(app, func(c echo.Context, user *User, _ *Player) error {
+		// Get IP from query param
+		ip := c.QueryParam("ip")
+		if ip == "" {
+			return c.String(http.StatusBadRequest, "missing required query parameter: ip")
+		}
+
+		// Get port (optional, default 25565)
+		port := 25565
+		portStr := c.QueryParam("port")
+		if portStr != "" {
+			p, err := strconv.Atoi(portStr)
+			if err != nil {
+				return c.String(http.StatusBadRequest, "invalid port value")
+			}
+			port = p
+		}
+
+		// Get player name
+		playerName := c.QueryParam("player")
+		if playerName == "" {
+			return c.String(http.StatusBadRequest, "missing required query parameter: player")
+		}
+
+		// Check if user owns the requested player
+		found := false
+		for _, currentPlayer := range user.Players {
+			if currentPlayer.Name == playerName {
+				found = true
+				break
+			}
+		}
+
+		if !found {
+			return c.NoContent(http.StatusUnauthorized)
+		}
+
+		return app.getMpPass(&c, playerName, ip, port)
+	})
+}