ccuetoh / fossil

Go wrapper for the Pterodactyl and WISP APIs

Fossil

Fossil is a pure Go wrapper library for the Pterodactyl API and it's descendants. It allows client-wise and administrator-wise operations for easy and automated server, user, node, egg and location management.

Contents:

• Installation
• Examples
  • Client API
    • Servers
      • Fetch
      • Status and usage
    • Server Actions
      • Turn on/off
      • Execute commands
  • Application API
    • Servers
      • Fetch
      • Create
      • Modify
      • Suspend/Unsuspend
      • Reinstall or rebuild
    • Databases
      • Fetch
      • Create
      • Delete
    • Users
      • Fetch
      • Modify
      • Create
      • Delete
    • Nests and eggs
      • Fetch nests
      • Fetch eggs
    • Locations
      • Fetch
      • Create
      • Modify
      • Delete
• Disclaimer
• Licence

Installation

Fossil can be installed using the integrated Go package manager:

go get github.com/camilohernandez/fossil

Examples

Client API

A Client gets access to all the functionalities a user might find on their server control panel. A Client Token is requiered for the Creation of a Client. To start a new Client use the NewClient() function:

import "github.com/camilohernandez/fossil"

client := fossil.NewClient("https://example.com","NRVW42TME45WW3B3E5VTWOZ3MFZWIYLTMRQXGZDBMFZWIYLT") // Panel URL and Client Token

Servers

Fetch all servers

servers, err := client.GetServers()
if err != nil {
    fmt.Println("ERROR: " + err.Error())
    return
}

for _, s := range servers {
    fmt.Printf("ID: %s\n", s.ID)
    fmt.Printf("Name: %s\n", s.Name)
    fmt.Printf("Description: %s\n", s.Description)
}

Fetch a specific server

server, err := client.GetServer("6a185444")
if err != nil {
    fmt.Println("ERROR: " + err.Error())
    return
}

fmt.Printf("ID: %s\n", server.ID)
fmt.Printf("Name: %s\n", server.Name)
fmt.Printf("Description: %s\n", server.Description)

Get a server's status and usage

status, err := client.GetServerStatus("6a185444")
if err != nil {
    fmt.Println("ERROR: " + err.Error())
    return
}

fmt.Printf("State: %s\n", status.State)
fmt.Printf("CPU Current: %f\n", server.CPU.Current)
fmt.Printf("Memory used: %d\n", server.Memory.Used)
fmt.Printf("Disk used: %s\n", server.Disk.Used)

Server Actions

Turn server on

err := client.SetPowerState("6a185444", fossil.ON)
if err != nil {
    fmt.Println("ERROR: " + err.Error())
    return
}

Execute a command on a server

err := client.ExecuteCommand("6a185444", "say Hello!")
if err != nil {
    fmt.Println("ERROR: " + err.Error())
    return
}

Application API

An Application connection allows full access to server, user, location, nest and egg management. With Application calls you have full administrator-level access to the creation of users and servers. An Application Token (also called "API Token") is required to create an Application object. To start a new Application use the NewApplication() function:

import "github.com/camilohernandez/fossil"

app := fossil.NewApplication("https://example.com","OF3WK4LXMVYXOZLYMRQXQWTYMFZWIYLTMRQXGZDBOM") // Panel URl and Application Token

Servers

When interacting servers with an Application Token you get extra information, and more functions.

Fetch all servers

servers, err := app.GetServers()
if err != nil {
    fmt.Println("ERROR: " + err.Error())
    return
}

for _, s := range servers {
    fmt.Printf("ID: %d\n", s.ID)
    fmt.Printf("Name: %s\n", s.Name)
    fmt.Printf("Description: %s\n", s.Description)
    fmt.Printf("Node: %d\n", s.Node)
    fmt.Printf("Nest: %d\n\n", s.Nest)
}

Get a server with its Internal ID

server, err := app.GetServer(17)
if err != nil {
    fmt.Println("ERROR: " + err.Error())
    return
}

Get a server with its External ID

server, err := app.GetServerExternal("test_server1")
if err != nil {
    fmt.Println("ERROR: " + err.Error())
    return
}

Create a new server

server := &fossil.ApplicationServer{
    Name:        "Test Server",
    Description: "A server to test the Fossil library",
    ExternalID:  "test_server1",
    User:        12,
    Node:        2,
    Nest:        5,
    Egg:         20,
    Container: fossil.Container{
        StartupCommand: "java -Xms128M -Xmx 1024M -jar server.jar",
        Image:          "quay.io/pterodactyl/core:java-glibc", // Minecraft
        Environment: map[string]string{ // WISP Requieres some aditional enviroment variables for SRCDS images:
            "DL_VERSION": "1.12.2",     // SRCDS_APPID, STEAM_ACC, SRCDS_MAP
        },
    },
    Limits: fossil.Limits{
        Memory:    512,
        Swap:      512,
        Disk:      1024,
        IO:        500,
        CPU:       100,
        Databases: 1,
    },
    Allocation: 9000,
}

err := app.CreateServer(server)
if err != nil {
    fmt.Println("ERROR: " + err.Error())
    return
}

Change a server's name, user, external ID or description

sv, err := app.GetServer(17)
if err != nil {
    fmt.Println(err.Error())
    return
}

sv.Name = "Fossil Test"

err = app.UpdateDetails(sv)
if err != nil {
    fmt.Println(err.Error())
}

Change a server's limits or allocations

sv, err := app.GetServer(17)
if err != nil {
    fmt.Println(err.Error())
    return
}

sv.Limits = fossil.Limits{
    Memory:      1024,
    Databases:   2,
    Allocations: 2,
}

err = app.UpdateBuild(sv, []int{9001, 9002},[]int{9000}) // Add allocations 9001 and 9002, delete 9000
if err != nil {
    fmt.Println(err.Error())
    return
}

Change a server's image settings

sv, err := app.GetServer(17)
if err != nil {
    fmt.Println(err.Error())
    return
}

sv.Container = fossil.Container{
    StartupCommand: "java -Xms128M -Xmx 1024M -jar server.jar",
    Image:          "quay.io/pterodactyl/core:java-glibc", // Minecraft
    Environment: map[string]string{
        "DL_VERSION": "1.12.2",
    },
}

err = app.UpdateStartup(sv)
if err != nil {
    fmt.Println(err.Error())
    return
}

Suspend or unsuspend a server

err := app.SuspendServer(17) // Suspending server with Internal ID 17 
if err != nil {
    fmt.Println(err.Error())
    return
}

err = app.UnsuspendServer(17) // Unsuspending server with Internal ID 17 
if err != nil {
    fmt.Println(err.Error())
    return
}

Rebuild or reinstall a server

err := app.RebuildServer(17) // Rebuilding server with Internal ID 17
if err != nil {
    fmt.Println(err.Error())
    return
}

err = app.ReinstallServer(17) // Reinstalling server with Internal ID 17
if err != nil {
    fmt.Println(err.Error())
    return
}

Delete a server

err := app.DeleteServer(17) // Deleting server with Internal ID 17
if err != nil {
    fmt.Println(err.Error())
    return
}

err = app.ForceDeleteServer(17) // DeleteServer should allays be preferred, as ForceDeleteServer
if err != nil {                 // is an unsafe operation.
    fmt.Println(err.Error())
    return
}

Databases

Fetch all databases

dbs, err := app.GetDatabases()
if err != nil {
    fmt.Println(err.Error())
    return
}

for _, db := range dbs{
    fmt.Println(db.Database)
}

Fetch a specific database

db, err := app.GetDatabase(17, 1) // Get database 1 in server 17
if err != nil {
    fmt.Println(err.Error())
    return
}

Create a database

db := &fossil.Database{
    Database: "fossil_test",
    Host:      15, // The server 15 will be the host server
    Remote:    "%", // IPs and wildcards work
}

err := app.CreateDatabase(17, db)
if err != nil {
    fmt.Println(err.Error())
    return
}

Delete a database

err := app.DeleteDatabase(17, 1) // Delete database 1 in server 17
if err != nil {
    fmt.Println(err.Error())
    return
}

Users

Fetch all users

users, err := app.GetUsers()
if err != nil {
    fmt.Println("ERROR: " + err.Error())
    return
}

for _, u := range users {
    fmt.Printf("ID: %d\n", u.ID)
    fmt.Printf("First Name: %s\n", u.FirstName)
    fmt.Printf("Last Name: %s\n\n", u.LastName)
}

Fetch a specific user

user, err := app.GetUser(4) // Get user of Internal ID 4
if err != nil {
    fmt.Println("ERROR: " + err.Error())
    return
}

Create a user

user := &fossil.User{
    ExternalID:              "test_user1",
    Username:                "TestUser",
    Email:                   "[e-mail]",
    FirstName:               "John",
    LastName:                "Doe",
}

err := app.CreateUser(user, "password123")
if err != nil {
    fmt.Println("ERROR: " + err.Error())
    return
}

Update a user

user, err := app.GetUser(17)
if err != nil {
    return
}

user.FirstName = "John"

err = app.UpdateUser(user, "password123") // Password is optional
if err != nil {
    fmt.Println("ERROR: " + err.Error())
    return
}

Delete a user

err := app.DeleteUser(17)
if err != nil {
    return
}

Nests and eggs

Fetch nests

nests, err := app.GetNests()
if err != nil {
    fmt.Println(err.Error())
    return
}

for _, n := range nests{
    fmt.Println(n.Name)
    fmt.Println(n.Description)
}

Fetch specific nest

nest, err := app.GetNest(2) // Get nest with ID 2 (Minecraft)
if err != nil {
    fmt.Println(err.Error())
    return
}

Fetch eggs inside a nest

eggs, err := app.GetEggs(2) // Get all the eggs for nest 2 (Minecraft)
if err != nil {
    fmt.Println(err.Error())
    return
}

for _, e := range eggs{
    fmt.Println(e.ID)
    fmt.Println(e.Description)
}

Fetch specific egg inside a nest

egg, err := app.GetEgg(2, 2)
if err != nil {
    fmt.Println(err.Error())
    return
}

Locations

Fetch locations

locs, err := app.GetLocations()
if err != nil {
    fmt.Println(err.Error())
    return
}

for _, l := range locs{
    fmt.Println(l.ID)
    fmt.Println(l.Long)
}

Fetch location

loc, err := app.GetLocation(2) // Get location with ID 2
if err != nil {
    fmt.Println(err.Error())
    return
}

Fetch location

loc, err := app.GetLocation(2) // Get location with ID 2
if err != nil {
    fmt.Println(err.Error())
    return
}

Create a location

loc, err := app.CreatLocation("us.gameserver1", "USA Gameserver #1") // Short and long name
if err != nil {
    fmt.Println(err.Error())
    return
}

Modify a location's names

loc := GetLocation(2)

loc.ShortName = "us.datacenter"
loc.LongName = "US Datacenter"

err := app.UpdateLocationName(loc)
if err != nil {
    fmt.Println(err.Error())
    return
}

Delete a location

err := app.DeleteLocation(2) // Delete location with ID 2
if err != nil {
    fmt.Println(err.Error())
    return
}

Disclaimer

Fossil is partially based on the Crocgodyl library. All the respective kudos to the author.

Licence

This library is licensed under the MIT Licence, please refer to the LICENCE file for more information. The logo used in this project is provided by OpenClipart-Vectors, and is licenced under the Pixbay Licence.