vrage

README

go-vrage

go-vrage is a Go client for the VRage Remote API of Space Engineers 1.

It can be used to programmatically manage and monitor Dedicated Servers, including retrieving server status, managing players, and executing server commands.

⚠️ WARNING: This project is in an early development stage. Breaking changes may be introduced without prior notice. Use in production environments is strongly discouraged. When the first stable release is published, this notice will be removed.

Features

• Abstracted HMAC Authentication: Automatically manages nonces, timestamps, and HMAC-SHA1 signature generation.
• Dual Response Format: Delivers strongly typed Go structs while preserving raw JSON payload bytes for custom parsing or logging.
• Idiomatic Error Handling: Maps API responses into custom Go error types for straightforward error inspection.
• Context Support: Full context.Context propagation for timeout control and request cancellation across all endpoints.
• Customizable HTTP Client: Easily inject custom http.Client instances or middleware configurations.

Installation

To install the package to your Go module, run the following command:

go get -u github.com/space-engineers-tools/go-vrage

Usage

⚠️ SECURITY NOTICE: Never hardcode your security key in source code. Use environment variables for serious applications. The example below is for demonstration purposes only.

package main

import (
    "fmt"
    "time"

    "github.com/space-engineers-tools/go-vrage"
)

func main() {
    // Create a new VRage client with your server configuration
    client := vrage.NewClient(vrage.ClientConfig{
        BaseURL:     "your-base-url",
        SecurityKey: "your-security-key",
    })

    status, err := client.Server()
    if err != nil {
        fmt.Println("Error retrieving server status:", err)
        return
    }
    fmt.Println("Server status:", status)
}

Contributing

We welcome contributions! Please read our contributing guidelines for details on how to get started.

Disclaimer

This project is not affiliated with Keen Software House or the Space Engineers game.

Documentation

Overview

Package vrage provides a client for interacting with the Space Engineers VRage Remote API.

Before using this package, check your SpaceEngineers-Dedicated.cfg and ensure the following setting is enabled:

<RemoteApiEnabled>true</RemoteApiEnabled>

Index

• Constants
• Variables
• func ToPtr[T any](value T) *T
• type Client
  • func NewClient(config ClientConfig) *Client
  • func (c *Client) Config() ClientConfig
• type ClientConfig
  • func (c *ClientConfig) Validate() error
• type Sender

Constants

const (
	DefaultTimeout     time.Duration = 10 * time.Second
	DefaultAPIEndpoint string        = "/vrageremote"
	DefaultContentType string        = "application/json"
	DefaultPort        uint32        = 8080
)

const Repository string = "github.com/space-engineers-tools/go-vrage"

Repository is the module path for the go-vrage package

Variables

var (
	ErrConnectionFailed   = errors.New("failed to connect to the server: check if the server is running and reachable")
	ErrInvalidSecurityKey = errors.New("server returned StatusForbidden: security key is invalid or missing")
	ErrRequestTimeout     = errors.New("request timed out: the server did not respond in time")
)

var Version string = func() string {
	info, ok := debug.ReadBuildInfo()
	if !ok {
		return "unknown"
	}

	for _, dep := range info.Deps {
		if dep.Path == Repository {

			return strings.TrimPrefix(dep.Version, "v")
		}
	}

	return "dev"
}()

Version is the current version of the go-vrage package

Functions

func ToPtr

func ToPtr[T any](value T) *T

ToPtr returns a pointer to the given value.

Types

type Client

type Client struct {
	// Sender is the underlying request executor for the Client.
	//
	// While it can be used directly for raw requests, it's recommended to use the
	// high-level methods provided by Client for type safety and convenience.
	Sender *Sender
}

Client is the high-level API client for the Space Engineers VRage Remote API.

It provides typed methods for interacting with server endpoints. Before using this client, ensure <RemoteApiEnabled> is set to true in SpaceEngineers-Dedicated.cfg and the target server is running.

func NewClient

func NewClient(config ClientConfig) *Client

NewClient creates a new Client instance with the provided configuration.

func (*Client) Config

func (c *Client) Config() ClientConfig

GetConfig returns the ClientConfig of the current Client instance.

Be careful not to leak sensitive information, such as the SecurityKey, when using this function.

type ClientConfig

type ClientConfig struct {
	// RemoteApiIP is the IP address or DNS name of the Space Engineers server.
	//
	// Corresponding Setting in SpaceEngineers-Dedicated.cfg:
	//  <RemoteApiIP>
	//
	// Examples:
	//  "127.0.0.1"
	//  "example.com"
	//  "play.cool-server.com"
	RemoteApiIP string `validate:"required,ip|fqdn"`

	// RemoteSecurityKey is the security key used for authenticating API requests.
	//
	// Corresponding Setting in SpaceEngineers-Dedicated.cfg:
	// 	<RemoteSecurityKey>
	RemoteSecurityKey string `validate:"required"`

	// RemoteApiPort is the port of the Remote API on the Space Engineers server.
	//
	// Corresponding Setting in SpaceEngineers-Dedicated.cfg:
	//  <RemoteApiPort>
	//
	// Default:
	//  8080
	RemoteApiPort uint32 `validate:"port"`

	// Timeout specifies the maximum duration for an API request before an vrage.ErrRequestTimeout error is returned.
	//
	// Default:
	//  vrage.DefaultTimeout
	Timeout time.Duration `validate:"gte=0"`

	// UseHTTPS indicates whether to use HTTPS for API requests.
	//
	// Note: While the Space Engineers server does not natively support HTTPS, this option
	// can be used when routing through a reverse proxy.
	//
	// Default:
	//  false
	UseHTTPS bool `validate:"-"`

	// APIEndpoint is the base route path for API requests.
	//
	// Note: While this path is fixed by the Space Engineers server, this option
	// allows customization when routing through a reverse proxy.
	//
	// Example: "/custompath", "/api/vrageremote", "/", or ""
	//
	// Default:
	//  ToPtr(DefaultAPIEndpoint)
	APIEndpoint *string `validate:"-"`

	// HttpClient allows the use of a custom HTTP client for making requests.
	//
	// If not provided, a default client with the specified Timeout will be used.
	//
	// Warning: when using a custom HttpClient the Timeout field in ClientConfig will be ignored.
	// In this case, ensure the custom HttpClient has an appropriate timeout set to avoid hanging requests.
	HttpClient *http.Client `validate:"-"`
}

ClientConfig holds the configuration settings for the VRage Remote API client.

func (*ClientConfig) Validate

func (c *ClientConfig) Validate() error

validate checks the ClientConfig for required fields and valid values.

type Sender

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

Sender handles low-level HTTP request execution against the server.

It can be invoked directly if raw communication or custom response handling is needed.

Use at your own risk, as this bypasses the high-level abstractions provided by the Client.