go-hll-rcon: An implementation of the HLL RCon protocol in Go

An implementation of the Hell Let Loose RCon protocol in Go. The protocol itself is documented in a Community effort in this document.

Usage

Import the module as usual with go modules, then use it according to the example:

package main

import (
	"context"
	rcon "github.com/floriansw/go-hll-rcon/rconv2"
	"log/slog"
	"os"
	"strconv"
	"time"
)

func main() {
	logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelInfo}))
	port, err := strconv.Atoi(os.Getenv("PORT"))
	if err != nil {
		panic(err)
	}
	p, err := rcon.NewConnectionPool(rcon.ConnectionPoolOptions{
		Logger:   logger,
		Hostname: os.Getenv("HOST"),
		Port:     port,
		Password: os.Getenv("PASSWORD"),
	})
	if err != nil {
		panic(err)
	}

	ctx, cancel := context.WithDeadline(context.Background(), time.Now().Add(2*time.Second))
	err = p.WithConnection(ctx, func(c *rcon.Connection) error {
		m, err := c.GetAvailableMaps(ctx)
		if err != nil {
			println(err.Error())
			return err
		}
		for _, n := range m {
			println(n)
		}
		return nil
	})
	if err != nil {
		panic(err)
	}
	cancel()
}

Executing this code will list the available maps of the Hell Let Loose server.

Command Coverage

go-hll-rcon covers all available RCon commands from Hell Let Loose. The available commands are documented in rcon/connection.go.

Developing

The library is split up into two different features: the bare connection handling and the commands that the game server supports. While the bare connection handling (actually sending bytes to and receiving them from the game server) is developed by maintainers of this library, the commands are different.

Instead of maintaining the implementation of each and every single command manually, the code of these commands is mostly auto-generated. For that, we created a purpose-built code generator that consists of two parts.

The first one is a tool that uses this very library to fetch the command definition of all available commands from an online game-server via RCon. It will convert and extend these definitions into a single JSON document. This JSON document (definitions/hll_rcon.json) contains the information about what commands exist, what parameters they take and what their response looks like, if they have any. You can find this tool in tools/generate_definitions/cmd.go.

Based on the JSON document generated by the "Generate Definitions" tool, a code generator will generate the necessary client code. It will automatically create a method to expose the command on the Connection type, as well as the necessary request and response objects. Each command, including all the required go types, lives in their own file in rconv2/, prefixed with op_. You can find the code generator in codegen/generate.go and invoke it with tools/codegen/cmd.go .

On top of the auto-generated client code, several types and commands will have extended functionality. These extensions are maintained by the maintainers and live in rconv2/ files prefixed with ext_ followed by the command name they extend.