pickaxx

README

Pickaxx

A standalone web console for managing a Minecraft server instance.

The goals of this project are as follows:

• Minimal configuration, sane defaults (drop a server into the tool and go)
• Single binary, small memory footprint
• Basic authentication

Current state

• In development. It can start an existing minecraft server and send/receive output, but not much else.
• It can not yet bootstrap new server instances (i.e. drag and drop).
• It does not handle any authentication yet, making it not yet able to run safely on a public server.

Developer Setup

1. Install gowatch

go get -u github.com/silenceper/gowatch

1. Until this tool can bootstrap new Minecraft instances on it's own, manually download server.jar from Minecraft's site (see below), and copy this into the path testserver/server.jar.
2. Run tests (or use make test).
3. Run make which will start the server. Load http://localhost:8080

Dependencies

• This project uses go-watch to run/restart the server.
• Compatible Java runtime (tested on OpenJDK 15.0.1).
• Minecraft server (tested on 1.16.4).

Documentation

Index

• Constants
• Variables
• type ClientManager
  • func (c *ClientManager) AddClient(conn *websocket.Conn)
  • func (c *ClientManager) Close() error
  • func (c *ClientManager) Write(data []byte) (int, error)
• type ProcessManager
  • func (m *ProcessManager) Active() bool
  • func (m *ProcessManager) CanAcceptCommands() bool
  • func (m *ProcessManager) CurrentState() ServerState
  • func (m *ProcessManager) RecentActivity() []string
  • func (m *ProcessManager) Start(w io.Writer) error
  • func (m *ProcessManager) Stop() error
  • func (m *ProcessManager) Submit(command string) error
• type ServerState
  • func (i ServerState) String() string
• type StatusNotifier
  • func (n *StatusNotifier) Notify(st ServerState)
  • func (n *StatusNotifier) Register(states []ServerState) <-chan ServerState
  • func (n *StatusNotifier) Unregister(ch <-chan ServerState)

Constants

const (
	// MaxMem is the maximum allocated memory
	MaxMem = "-Xmx1024m"

	// MinMem is the minimum allocated memory
	MinMem = "-Xms512m"

	// JarFile is the name of the server jar as it exists on disk
	JarFile = "server.jar"

	// DefaultPort is the default minecraft server port
	DefaultPort = 25565

	// DefaultWorkingDir is the default working directory
	DefaultWorkingDir = "testserver"
)

Variables

var (
	// DefaultCommand is the name of the executable.
	DefaultCommand = []string{"java", MaxMem, MinMem, "-jar", JarFile, "nogui"}
)

var ErrInvalidClient = errors.New("client not valid")

ErrInvalidClient occurs when a client is not valid.

var ErrNoProcess = errors.New("no process running")

ErrNoProcess occurs when no process exists to take an action on.

var ErrProcessExists = errors.New("unable to start new process")

ErrProcessExists exists when a new server process can not be started.

Types

type ClientManager

type ClientManager struct {
	// contains filtered or unexported fields
}

ClientManager is a collection of clients

func (*ClientManager) AddClient

func (c *ClientManager) AddClient(conn *websocket.Conn)

AddClient adds a new client to this manager

func (*ClientManager) Close

func (c *ClientManager) Close() error

Close will close any client connections and clean up resources used by this manager.

func (*ClientManager) Write

func (c *ClientManager) Write(data []byte) (int, error)

Write will send data down a channel to be sent to clients. This operation must write to a channel, as writes to an underlying websocket can not happen concurrently.

type ProcessManager

type ProcessManager struct {
	// Command is the command & arguments passed when 'Start()' is
	// invoked. If not set, it will default to 'DefaultExecArgs'.
	Command []string

	// WorkingDir is our starting directory. If not set, will default
	// to 'DefaultWorkignDir'
	WorkingDir string
	// contains filtered or unexported fields
}

ProcessManager manages the Minecraft server's process lifecycle.

func (*ProcessManager) Active

func (m *ProcessManager) Active() bool

Active returns whether the process is running.

func (*ProcessManager) CanAcceptCommands

func (m *ProcessManager) CanAcceptCommands() bool

CanAcceptCommands returns true if this instance can direct commands through to the process.

func (*ProcessManager) CurrentState

func (m *ProcessManager) CurrentState() ServerState

CurrentState is the current running state of the process being managed.

func (*ProcessManager) RecentActivity

func (m *ProcessManager) RecentActivity() []string

RecentActivity will return the latest content contained in this server's log file.

func (*ProcessManager) Start

func (m *ProcessManager) Start(w io.Writer) error

Start will initialize a new process, sending all output to the provided io.Writer, and set values on this object to track process state. This will return an error if the process is already running.

func (*ProcessManager) Stop

func (m *ProcessManager) Stop() error

Stop will halt the current process by sending a direct shutdown command. This will also kill the process if it does not respond in a given timeframe.

func (*ProcessManager) Submit

func (m *ProcessManager) Submit(command string) error

Submit will submit a new command to the underlying minecraft process. Any output is returned asynchonously in the processing loop. Prefixed slash-commands will have slashes trimmed (e.g. "/help" -> "help")

type ServerState

type ServerState int

ServerState describes the current state of a Minecraft server.

const (
	Unknown ServerState = iota
	Starting
	Running
	Stopping
	Stopped
)

Server Statuses

func (ServerState) String

func (i ServerState) String() string

type StatusNotifier

type StatusNotifier struct {
	sync.Mutex
	// contains filtered or unexported fields
}

StatusNotifier handles a registery for observers of server state. This implementation can be accessed concurrently by multiple goroutines.

func (*StatusNotifier) Notify

func (n *StatusNotifier) Notify(st ServerState)

Notify will notify observers of the given parameters that the state has changed to the provided value.

func (*StatusNotifier) Register

func (n *StatusNotifier) Register(states []ServerState) <-chan ServerState

Register will register a new observer for the given states. Returns a new channel which will receive messages when the server changes to any of the state(s) provided.

func (*StatusNotifier) Unregister

func (n *StatusNotifier) Unregister(ch <-chan ServerState)

Unregister will remove the given channel from the set of observers. The channel will be closed, and no further updates will be sent.