vrage

README

go-vrage

go-vrage is a Go client for the VRage Remote API, which is used by Space Engineers 1 Dedicated Servers to expose server management functionality over HTTP.

[!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

coming soon

API Coverage

Endpoint	Status
/v1/server
/v1/admin
/v1/session

Installation

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

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

Usage

Please check out the examples directory for usage examples.

Contributing

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

Links

• Usage Examples
• Space Engineers Dedicated Servers Docs

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 IsResponseSuccessful(resp *http.Response) bool
• type APIAdmin
• type APIServer
  • func (s *APIServer) Ping() (BaseResponse[APIServerPingData], error)
  • func (s *APIServer) Status() (BaseResponse[APIServerStatusData], error)
  • func (s *APIServer) Stop() error
• type APIServerPingData
• type APIServerStatusData
• type APISession
• type BaseResponse
• type Client
  • func NewClient(config ClientConfig) (*Client, error)
• type ClientConfig
  • func (c *ClientConfig) SetDefaults()
  • func (c *ClientConfig) Validate() error
• type HTTPClient
  • func (c *HTTPClient) DeleteV1Server() (*http.Response, error)
  • func (c *HTTPClient) Do(method httpMethod, endpoint string, jsonPayload jsonMap, headers httpHeaders) (*http.Response, error)
  • func (c *HTTPClient) DoErr(method httpMethod, endpoint string, jsonPayload jsonMap, headers httpHeaders) (*http.Response, error)
  • func (c *HTTPClient) GetV1ServerPing() (*http.Response, error)
  • func (c *HTTPClient) GetV1ServerStatus() (*http.Response, error)
• type Meta

Constants

const (
	DefaultTimeout      time.Duration = time.Second * 5
	DefaultBaseEndpoint string        = "/vrageremote"
	DefaultPort         uint32        = 8080
)

Default configuration values for the VRage Remote API client.

Variables

var (
	ErrConfigIncomplete   = errors.New("invalid config: missing required fields")
	ErrConfigInvalid      = errors.New("invalid config: field validation failed")
	ErrConfigIncompatible = errors.New("invalid config: conflicting settings")
)

ErrConfig... are errors for configuration validation.

var (
	ErrAPIConnectionFailed   = errors.New("failed to connect to the server: connection refused or host not available")
	ErrAPIInvalidSecurityKey = errors.New("server returned StatusForbidden: security key is invalid or missing")
	ErrAPIRequestTimeout     = errors.New("request timed out: the server did not respond in time")
	ErrAPIUnexpectedCode     = errors.New("unexpected status code from the server")
	ErrAPIUnexpectedBody     = errors.New("unexpected response body from the server")
)

ErrAPI... are errors for API request failures.

Functions

func IsResponseSuccessful

func IsResponseSuccessful(resp *http.Response) bool

IsResponseSuccessful checks if the HTTP response starts with 2.

Types

type APIAdmin

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

APIAdmin provides access to the /v1/admin API routes.

type APIServer

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

APIServer provides access to the /v1/server API routes.

func (*APIServer) Ping

func (s *APIServer) Ping() (BaseResponse[APIServerPingData], error)

Ping returns a ping response from the server, which can be used to check if the server is reachable and responding.

func (*APIServer) Status

func (s *APIServer) Status() (BaseResponse[APIServerStatusData], error)

Status returns the current status of the server. This includes information about the performance and the world.

func (*APIServer) Stop

func (s *APIServer) Stop() error

Stop stops the server. Some hosting providers may restart the server instead of stopping it, depending on their configuration.

Use with caution.

type APIServerPingData

type APIServerPingData struct {
	Result string `json:"result"`
}

APIServerPingData represents the data returned by the GET /v1/server/ping endpoint.

type APIServerStatusData

type APIServerStatusData struct {
	Game              string  `json:"Game"`
	IsReady           bool    `json:"IsReady"`
	PirateUsedPCU     int     `json:"PirateUsedPCU"`
	Players           int     `json:"Players"`
	ServerID          int64   `json:"ServerId"`
	ServerName        string  `json:"ServerName"`
	SimSpeed          float64 `json:"SimSpeed"`
	SimulationCPULoad float64 `json:"SimulationCpuLoad"`
	TotalTime         int     `json:"TotalTime"`
	UsedPCU           int     `json:"UsedPCU"`
	Version           string  `json:"Version"`
	WorldName         string  `json:"WorldName"`
}

APIServerStatusData represents the data returned by the GET /v1/server endpoint.

type APISession

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

APISession provides access to the /v1/session API routes.

type BaseResponse

type BaseResponse[T any] struct {
	Data T    `json:"data"`
	Meta Meta `json:"meta"`
}

BaseResponse represents the base response structure of the API.

type Client

type Client struct {
	Config  ClientConfig
	HTTP    HTTPClient
	Session APISession
	Server  APIServer
	Admin   APIAdmin
}

Client is the main entry point for interacting with the VRage API.

It provides access to various API endpoints through its sub-clients.

func NewClient

func NewClient(config ClientConfig) (*Client, error)

NewClient creates a new Client instance with the provided configuration.

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"` //nolint:revive // so the name is closer to the .cfg file

	// 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"` //nolint:revive // so the name is closer to the .cfg file

	// 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:"-"`

	// BaseEndpoint 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", "/", or ""
	//
	// Default:
	//  ToPtr(DefaultAPIEndpoint)
	BaseEndpoint *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) SetDefaults

func (c *ClientConfig) SetDefaults()

SetDefaults initializes default values for ClientConfig fields that are not explicitly set.

func (*ClientConfig) Validate

func (c *ClientConfig) Validate() error

Validate checks the ClientConfig for required fields and valid values.

type HTTPClient

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

HTTPClient handles all HTTP requests.

func (*HTTPClient) DeleteV1Server

func (c *HTTPClient) DeleteV1Server() (*http.Response, error)

DeleteV1Server stops the server and returns the HTTP response.

returns 200 OK with empty body if the server was successfully stopped

DELETE /v1/server

func (*HTTPClient) Do

func (c *HTTPClient) Do(
	method httpMethod,
	endpoint string,
	jsonPayload jsonMap,
	headers httpHeaders,
) (*http.Response, error)

Do sends an HTTP request to the API with the specified method, endpoint, JSON payload, and headers and returns the pure HTTP response and error without any wrapping.

func (*HTTPClient) DoErr

func (c *HTTPClient) DoErr(
	method httpMethod,
	endpoint string,
	jsonPayload jsonMap,
	headers httpHeaders,
) (*http.Response, error)

DoErr sends an HTTP request to the API with the specified method, endpoint, JSON payload, and headers and returns the HTTP response and high level sentinel errors defined in errors.go.

func (*HTTPClient) GetV1ServerPing

func (c *HTTPClient) GetV1ServerPing() (*http.Response, error)

GetV1ServerPing fetches a ping response from the server and returns the HTTP response.

GET /v1/server/ping

func (*HTTPClient) GetV1ServerStatus

func (c *HTTPClient) GetV1ServerStatus() (*http.Response, error)

GetV1ServerStatus fetches the current status of the server and returns the HTTP response.

GET /v1/server

type Meta

type Meta struct {
	// APIVersion is the version of the API.
	APIVersion string `json:"apiVersion"`
	// QueryTime is the time taken (in seconds) to process the request.
	QueryTime float64 `json:"queryTime"`
}

Meta represents the metadata of the API response.