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.

Index

• Constants
• Variables
• type Client
  • func NewClient(config ClientConfig) *Client
  • func (c *Client) Config() ClientConfig
• type ClientConfig
• type Sender

Constants

const (
	DefaultTimeout     time.Duration = 10 * time.Second
	DefaultAPIEndpoint string        = "/vrageremote"
)

Variables

var (
	ErrInvalidConfig = errors.New("invalid client configuration: missing required fields")
)

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 {
	// BaseURL is the root URL of the Space Engineers server
	//
	// Ensure the port matches the <RemoteApiPort> setting in SpaceEngineers-Dedicated.cfg.
	//
	// Example: "http://localhost:8080"
	BaseURL string

	// SecurityKey is a key used for authentication with the API server.
	//
	// This corresponds to the <RemoteSecurityKey> tag in SpaceEngineers-Dedicated.cfg.
	SecurityKey string

	// Timeout specifies the maximum duration for an individual API request.
	// If a request exceeds this duration, context.DeadlineExceeded is returned.
	//
	// Default: vrage.DefaultTimeout
	Timeout time.Duration

	// 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.
	//
	// Default: vrage.DefaultAPIEndpoint
	APIEndpoint string

	// 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
}

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

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.