aternos_api

package module
v0.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 10, 2023 License: GPL-3.0 Imports: 20 Imported by: 3

README

Aternos API

Unofficial aternos.org API, initially inspired by the now deprecated AternosAPI python library. Also 'bypasses' cloudflare without resorting to browser automation or other stupid hacks.

Disclaimer

This is NOT an AFK bot and never will be! Please be respectful and don't abuse an awesome free service such as Aternos. I do not take any responsibility for what you do with this solution, but I will gladly take this repository down if it results in abuse of the service.

By using this package you are automatically breaking the TOS. In other words your account could be suspended at any time. Use at your own risk.

Usage

Library

See examples (easy) or the CLI source code (advanced). See also the auto-generated pkg.go.dev reference documentation here.

CLI

This project also comes with a simple command line application to start and stop your server.

Download the binary for your operating system from releases.

OR:

Manual build & usage instructions:

$ git clone https://github.com/sleeyax/aternos-api.git
$ cd aternos-api
$ go mod download
$ go run cmd/main.go

Unfortunately the command go install github.com/sleeyax/aternos-api@latest is not supported due to a limitation in go regarding 'replace directives'.

Projects

Projects that are using this package:

Made something cool? Let me know or create a PR to add your project to this list!

License

Licensed under GNU General Public License v3.0.

TL;DR:

You may copy, distribute and modify the software as long as you track changes/dates in source files. Any modifications to or software including (via compiler) GPL-licensed code must also be made available under the GPL along with build & install instructions.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ServerAlreadyStartedError = errors.New("server already started")

	ServerAlreadyStoppedError = errors.New("server already stopped")

	// UnauthenticatedError indicates an invalid account was used to request the resource.
	UnauthenticatedError = errors.New("unauthenticated (invalid account)")

	// ForbiddenError indicates that the request was blocked by CloudFlare.
	ForbiddenError = errors.New("forbidden (blocked by CloudFlare)")
)

Functions

This section is empty.

Types

type Api 

type Api struct {
	Options *Options
	// contains filtered or unexported fields
}

func New 

func New(options *Options) *Api

New allocates a new Aternos API instance.

func (*Api) ConfirmServer 

func (api *Api) ConfirmServer(ctx context.Context, delay time.Duration) error

ConfirmServer sends a confirmation over HTTP to claim that 'you're still active'. You should call this function once it's your turn in queue, after the server has started.

This function will run synchronously if no context is given (nil value).

Delay specifies the amount of seconds to wait before submitting the next confirmation. Recommended to wait time is around 10 seconds.

func (*Api) ConnectWebSocket 

func (api *Api) ConnectWebSocket() (*Websocket, error)

ConnectWebSocket connects to the Aternos websockets server.

func (*Api) GetCookies 

func (api *Api) GetCookies() []*http.Cookie

GetCookies returns the current authentication cookies that are being used.

You can use this function to export them (to for example a .txt file) so you can resume the session later.

func (*Api) GetServerInfo 

func (api *Api) GetServerInfo() (ServerInfo, error)

GetServerInfo fetches all server information over HTTP.

func (*Api) StartServer 

func (api *Api) StartServer() error

StartServer starts your Minecraft server over HTTP.

func (*Api) StopServer 

func (api *Api) StopServer() error

StopServer stops the Minecraft server over HTTP. This function doesn't wait until the server is fully stopped, it only requests a shutdown.

type BackupProgress 

type BackupProgress struct {
	Id string `json:"id"`

	// Percentage the backup is done.
	Progress int `json:"progress"`

	Action string `json:"action"`

	Auto bool `json:"auto"`

	// Whether the backup is complete.
	Done bool `json:"done"`
}

type Data 

type Data struct {
	// Content contains either a regular string or a serialized JSON object.
	Content      string
	ContentBytes []byte
}

Data represents an arbitrary payload that can either contain a string or a variable object.

func (*Data) MarshalJSON 

func (d *Data) MarshalJSON() ([]byte, error)

func (*Data) UnmarshalJSON 

func (d *Data) UnmarshalJSON(data []byte) error

type Heap 

type Heap struct {
	// Used memory in bytes.
	Usage int `json:"usage"`
}

type Options 

type Options struct {
	// Initial authentication cookies.
	//
	// It must include at least ATERNOS_SESSION, ATERNOS_SERVER.
	//
	// It's recommended to also specify ATERNOS_LANGUAGE.
	Cookies []*http.Cookie

	// Optional HTTP proxy to use.
	Proxy *url.URL

	// Disables server SSL certificate checks.
	// It's recommended to enable this only for debugging purposes, such as debugging traffic with a web debugging/HTTP/MITM proxy.
	InsecureSkipVerify bool
}

type Queue 

type Queue struct {
	// Unique number to identify the queue.
	// This is usually 0.
	Number int `json:"queue"`

	// Current position in queue.
	// The higher the number, the longer you have to wait until it's your turn.
	Position int `json:"position"`

	// Amount of people in queue.
	Count int `json:"count"`

	// Percentage in the queue is calculated based on (Position / Count) * 100.
	Percentage float32 `json:"percentage"`

	// Status message.
	// E.g "waiting".
	Status string `json:"pending"`

	// Time left in human readable format.
	// E.g "ca. 1 min"
	Time string `json:"time"`

	// Minutes left to wait in number format.
	Minutes int `json:"minutes"`

	Jointime int `json:"jointime"`
}

Queue is the current status in queue. This struct is part of ServerInfo, unlike QueueReduction.

type QueueReduction added in v0.1.0 

type QueueReduction struct {
	// Unique number to identify the queue.
	// This is usually 0.
	Number int `json:"queue"`

	// Current total amount of people in queue.
	Total int `json:"total"`

	MaxTime int `json:"maxtime"`
}

QueueReduction is a simplified version of Queue that the server uses to notify queue reduction (queue_reduced).

type ServerInfo 

type ServerInfo struct {
	// Server brand.
	// Usually this is just "aternos".
	Brand string `json:"brand"`

	// Status code.
	Status ServerStatus `json:"status"`

	// Time since the server info, such as the status, has been updated.
	LastChanged int `json:"change"`

	// Maximum amount of players.
	MaxPlayers int `json:"slots"`

	// Number of logged issues or problems.
	Problems int `json:"problems"`

	// Amount of active players.
	Players int `json:"players"`

	// List of active players.
	PlayerList []string `json:"playerlist"`

	Message struct {
		Text  string `json:"text"`
		Class string `json:"class"`
	} `json:"message"`

	// Dynamic IP address.
	DynIP string `json:"dynip"`

	// Whether this is a server for bedrock edition.
	IsBedrock bool `json:"bedrock"`

	Host string `json:"host"`

	Port int `json:"port"`

	HeadStarts int `json:"headstarts"`

	RAM int `json:"ram"`

	// Status label
	// E.g. online, offline.
	StatusLabel string `json:"lang"`

	// Status label but in human-readable format.
	// E.g. Starting..., Online, Offline.
	StatusLabelFormatted string `json:"label"`

	// CSS class that's applied to the status label.
	StatusLabelClass string `json:"class"`

	// Amount of time left to join the server.
	Countdown int `json:"countdown"`

	Queue Queue `json:"queue"`

	// Unique server ID.
	Id string `json:"id"`

	// Name of the server.
	Name string `json:"name"`

	// Server software.
	Software string `json:"software"`

	SoftwareId string `json:"softwareId"`

	// Software type.
	// E.g vanilla, papermc.
	SoftwareType string `json:"type"`

	// Current Minecraft version.
	Version string `json:"version"`

	IsDeprecated bool `json:"deprecated"`

	// IP address.
	IP string `json:"ip"`

	// Domain address.
	Address string `json:"displayAddress"`

	// Message Of The Day.
	MOTD string `json:"motd"`

	// Name of the class that's used to display an icon next to the status.
	// E.g fa-stop-circle.
	Icon string `json:"icon"`

	DNS struct {
		Type    string   `json:"type"`
		Domains []string `json:"domains"`
		Host    string   `json:"host"`
		Port    int      `json:"port"`
		IP      string   `json:"ip"`
	} `json:"dns"`
}

type ServerStatus 

type ServerStatus int
const (
	Offline   ServerStatus = 0
	Online    ServerStatus = 1
	Preparing ServerStatus = 10
	Starting  ServerStatus = 2
	Stopping  ServerStatus = 3
	Saving    ServerStatus = 5
	Loading   ServerStatus = 6
)

type Tick 

type Tick struct {
	AverageTickTime float32 `json:"averageTickTime"`
}

type Websocket 

type Websocket struct {

	// Received messages channel.
	Message chan WebsocketMessage
	// contains filtered or unexported fields
}

func (*Websocket) Close 

func (w *Websocket) Close() error

Close closes the websocket connection.

func (*Websocket) IsConnected added in v0.3.0 

func (w *Websocket) IsConnected() bool

IsConnected returns whether we are connected.

func (*Websocket) Send 

func (w *Websocket) Send(message WebsocketMessage) error

Send sends a message over the websocket connection.

func (*Websocket) SendHeartBeat 

func (w *Websocket) SendHeartBeat() error

SendHeartBeat sends a single keep-alive request. The server doesn't respond to this request, but a heartbeat should be regularly sent to keep the connection alive.

func (*Websocket) SendHearthBeats 

func (w *Websocket) SendHearthBeats(ctx context.Context, duration ...time.Duration)

SendHearthBeats keeps sending keep-alive requests at a specified interval. If no interval is specified, a default is used. It's recommended to use the default value unless you have a good reason not to do so.

See Websocket.SendHeartBeat for more information.

func (*Websocket) StartConsoleLogStream 

func (w *Websocket) StartConsoleLogStream() error

StartConsoleLogStream starts fetching the server start logs (console). This function should only be called once the server has been started over HTTP.

func (*Websocket) StartHeapInfoStream 

func (w *Websocket) StartHeapInfoStream() error

StartHeapInfoStream starts fetching information about the server heap. See https://www.javatpoint.com/java-heap for more information about heaps.

func (*Websocket) StartTickStream 

func (w *Websocket) StartTickStream() error

StartTickStream starts streaming the current server tick count. See https://minecraft.fandom.com/wiki/Tick for more information about ticks.

func (*Websocket) StopConsoleLogStream 

func (w *Websocket) StopConsoleLogStream() error

StopConsoleLogStream starts fetching the server stop logs (console). This function should only be called once the server has been stopped over HTTP.

func (*Websocket) StopHeapInfoStream 

func (w *Websocket) StopHeapInfoStream() error

StopHeapInfoStream stops fetching information about the server heap. See https://www.javatpoint.com/java-heap for more information about heaps.

func (*Websocket) StopTickStream 

func (w *Websocket) StopTickStream() error

StopTickStream stops streaming the current server tick count. See https://minecraft.fandom.com/wiki/Tick for more information about ticks.

type WebsocketMessage 

type WebsocketMessage struct {
	Stream       string `json:"stream,omitempty"`
	Type         string `json:"type,omitempty"`
	Message      string `json:"Message,omitempty"`
	MessageBytes []byte `json:"-"`
	Data         Data   `json:"data,omitempty"`
	Console      string `json:"console,omitempty"`
}

Source Files

View all Source files

Directories

Path Synopsis
examples
simple-http
This example demonstrates how to start and stop a server over HTTP.
 This example demonstrates how to start and stop a server over HTTP.
simple-websocket
This example demonstrates how to start and stop a server over websockets.
 This example demonstrates how to start and stop a server over websockets.
internal
tlsadapter

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.