exaroton 1.5.1 → 1.7.0

package/README.md

@@ -1,8 +1,8 @@
 # Node.js exaroton API client
 
-### About
+## About
 The exaroton API allows automated access to some basic functionalities of your game servers, such as starting or stopping 
-the server. You can read the API documentation here: https://support.exaroton.com/hc/en-us/articles/360011926177
+the server. You can read the API documentation here: https://developers.exaroton.com
 
 This is the official Node.js implementation of this API.
 
@@ -12,10 +12,11 @@ This is the official Node.js implementation of this API.
 npm install exaroton
 ```
 
-### Usage
+## Usage
 To use the API and this client you have to get your API key, which you can generate in your exaroton account settings: https://exaroton.com/account
 
-#### Create a client object
+
+### Create a client object
 ```js
 const {Client} = require('exaroton');
 
@@ -23,13 +24,15 @@ const client = new Client(token);
 ```
 *Remember to keep your token secret and don't add it to any private or public code repositories.*
 
+### REST API
+
 #### Get account info
 ````js
 let account = await client.getAccount();
 console.log("My account is " + account.name + " and I have " + account.credits + " credits.");
 ````
 
-The account object contains the fields and information as listed in the [documentation](https://support.exaroton.com/hc/en-us/articles/360011926177#account).
+The account object contains the fields and information as listed in the [documentation](https://developers.exaroton.com/#account-get).
 
 #### List servers
 ```js
@@ -40,7 +43,7 @@ for(let server of servers) {
 }
 ```
 
-Each server object contains the fields and information as listed in the [documentation](https://support.exaroton.com/hc/en-us/articles/360011926177#servers).
+Each server object contains the fields and information as listed in the [documentation](https://developers.exaroton.com/#servers-get).
 
 #### Create a server object by ID
 ```js
@@ -65,7 +68,7 @@ if (server.hasStatus(server.STATUS.ONLINE)) {
     console.log("Server is offline.");
 }
 ```
-The server status is an `integer` as described in the [documentation](https://support.exaroton.com/hc/en-us/articles/360011926177#servers). You can use
+The server status is an `integer` as described in the [documentation](https://developers.exaroton.com/#header-server-status). You can use
 the [ServerStatus](./src/Server/ServerStatus.js) object, which you can require on its own `const {ServerStatus} = require('exaroton')` or via the
 shorthand `server.STATUS` property.
 
@@ -133,6 +136,25 @@ try {
 ```
 The RAM is set in full GiB and has to be between 2 and 16.
 
+#### Get the server MOTD
+```js
+try {
+    let motd = await server.getMOTD();
+    console.log(motd);
+} catch (e) {
+    console.error(e.message);
+}
+```
+
+#### Set the server MOTD
+```js
+try {
+    await server.setMOTD("Hello world!");
+} catch (e) {
+    console.error(e.message);
+}
+```
+
 #### Player lists
 A player list is a list of players such as the whitelist, ops or bans.
 Player list entries are usually usernames, but might be something else, e.g. IPs in the banned-ips list.
@@ -194,4 +216,87 @@ try {
 } catch (e) {
     console.error(e.message);
 }
+```
+
+### Websocket API
+The websocket API allows a constant connection to our websocket service to receive 
+events in real time without polling (e.g. trying to get the server status every few seconds).
+
+#### Server status events
+You can simply connect to the websocket API for a server by running the `subscribe()` function.
+```js
+server.subscribe();
+```
+
+By default, you are always subscribed to server status update events, you can
+react to server status changes by adding a listener:
+```js
+server.subscribe();
+server.on("status", function(server) {
+    console.log(server.status);
+});
+```
+This event is not only triggered when the status itself changes but also when other
+events happen, e.g. a player joins the server.
+
+#### Console
+There are several optional streams that you can subscribe to, e.g. 
+the console.
+```js
+server.subscribe("console");
+```
+The console stream emits an event for every new console line.
+```js
+server.subscribe("console");
+server.on("console:line", function(data) {
+    console.log(data.line);
+});
+```
+The `data.line` property is already cleaned up for easier use in this client library, you can use `data.rawLine` if you want the raw
+data with all formatting codes etc.
+
+The console stream also allows you to send commands directly over the websocket. This is faster because the connection is already
+established and no further authorization etc. is necessary. This library already checks if you are subscribed to the console stream
+and sends the command through that stream instead, so you can just use it the same way as before:
+```js
+try {
+    await server.executeCommand("say Hello world!");
+} catch (e) {
+    console.error(e.message);
+}
+```
+
+#### Tick times
+On Minecraft Java edition servers with version 1.16 and higher it is possible to get the tick times, and the TPS (ticks per second) of your server.
+This information is also available as an optional stream.
+```js
+server.subscribe("tick");
+server.on("tick:tick", function(data) {
+    console.log("Tick time: " + data.averageTickTime + "ms");
+    console.log("TPS: " + data.tps);
+});
+```
+
+#### RAM usage
+There are two different optional streams to get RAM usage, the general `stats` stream and the Java specific `heap` stream.
+It is recommended to use the `heap` stream if you are running a server software that is based on Java. It is not recommended using both.
+
+You can subscribe to multiple streams at once by passing an array to the subscribe function.
+```js
+server.subscribe(["stats", "heap"]);
+server.on("stats:stats", function(data) {
+    console.log(data.memory.usage);
+});
+server.on("heap:heap", function(data) {
+    console.log(data.usage);
+});
+```
+
+#### Unsubscribe
+You can unsubscribe from one, multiple or all streams using the `server.unsubscribe()` function.
+
+```js
+server.unsubscribe("console");
+server.unsubscribe(["tick", "heap"]);
+server.unsubscribe(); // this disconnects the websocket connection
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "exaroton",
-  "version": "1.5.1",
+  "version": "1.7.0",
   "description": "exaroton API client",
   "homepage": "https://exaroton.com",
   "main": "index.js",
@@ -12,6 +12,7 @@
   },
   "dependencies": {
     "form-data": "^3.0.1",
-    "got": "^11.8.2"
+    "got": "^11.8.2",
+    "ws": "^7.4.5"
   }
 }

package/src/Client.js

@@ -9,12 +9,27 @@ const GetServersRequest = require('./Request/GetServersRequest');
 const packageConfig = require('../package.json');
 
 class Client {
+    /**
+     * @type {string}
+     */
+    protocol = "https";
+
+    /**
+     * @type {string}
+     */
+    host = "api.exaroton.com";
+
+    /**
+     * @type {string}
+     */
+    basePath = "/v1/";
+
     /**
      * API base URL used for all requests
      *
      * @type {string}
      */
-    baseURL = "https://api.exaroton.com/v1/";
+    get baseURL() { return this.protocol + "://" + this.host + this.basePath }
 
     /**
      * API token used for authentication
@@ -56,6 +71,13 @@ class Client {
         return this;
     }
 
+    /**
+     * @return {string}
+     */
+    getAPIToken() {
+        return this.#apiToken;
+    }
+
     /**
      * Set the user agent
      *

package/src/Server/Server.js

@@ -1,3 +1,6 @@
+const EventEmitter = require('events');
+
+const WebsocketClient = require("../Websocket/WebsocketClient");
 const Software = require('./Software');
 const Players = require('./Players');
 const ServerStatus = require('./ServerStatus');
@@ -13,7 +16,7 @@ const GetServerOptionRequest = require('../Request/Server/GetServerOptionRequest
 const SetServerOptionRequest = require('../Request/Server/SetServerOptionRequest');
 const GetPlayerListsRequest = require('../Request/Server/PlayerLists/GetPlayerListsRequest');
 
-class Server {
+class Server extends EventEmitter {
     /**
      * Shorthand to get server status constants
      *
@@ -29,6 +32,11 @@ class Server {
      */
     #client;
 
+    /**
+     * @type {WebsocketClient}
+     */
+    #websocketClient;
+
     /**
      * Unique server ID
      *
@@ -113,10 +121,18 @@ class Server {
      * @param {string} id
      */
     constructor(client, id) {
+        super();
         this.#client = client;
         this.id = id;
     }
 
+    /**
+     * @return {Client}
+     */
+    getClient() {
+        return this.#client;
+    }
+
     /**
      * Get/update the server info
      *
@@ -163,9 +179,17 @@ class Server {
      * Execute a command in the server console
      *
      * @param {string} command
-     * @return {Promise<Response>}
+     * @return {Promise<Response|boolean>}
      */
     async executeCommand(command) {
+        if (this.#websocketClient && this.#websocketClient.hasStream("console")) {
+            /** @type {ConsoleStream} stream **/
+            let stream = this.#websocketClient.getStream("console");
+            if (stream.isStarted()) {
+                stream.sendCommand(command);
+                return true;
+            }
+        }
         return this.#client.request(new ExecuteServerCommandRequest(this.id, command));
     }
 
@@ -212,6 +236,24 @@ class Server {
         return this.setOption("ram", ram);
     }
 
+    /**
+     * Get the server MOTD
+     *
+     * @returns {Promise<string>}
+     */
+    getMOTD() {
+        return this.getOption("motd");
+    }
+
+    /**
+     * Set the server MOTD
+     *
+     * @param {string} motd
+     * @returns {Promise<Response>}
+     */
+    setMOTD(motd) {
+        return this.setOption("motd", motd);
+    }
 
     /**
      * Get a server option
@@ -284,6 +326,74 @@ class Server {
         return false;
     }
 
+    /**
+     * Get a websocket client for this server
+     *
+     * @return {WebsocketClient}
+     */
+    getWebsocketClient() {
+        if (!this.#websocketClient) {
+            this.#websocketClient = new WebsocketClient(this);
+            this.#websocketClient.on("status", (server) => this.emit("status", server));
+            this.#websocketClient.on("event", (data) => this.emit(data.stream + ":" + data.type, data.data));
+        }
+        return this.#websocketClient;
+    }
+
+    /**
+     * Subscribe to one or multiple streams
+     *
+     * @return {boolean}
+     * @param {string[]|string} streams
+     */
+    subscribe(streams) {
+        let websocketClient = this.getWebsocketClient();
+        if (!websocketClient.isConnected()) {
+            websocketClient.connect();
+        }
+        if (!streams) {
+            return;
+        }
+
+        if (typeof streams === "string") {
+            streams = [streams];
+        }
+
+        for (let stream of streams) {
+            let websocketStream = websocketClient.getStream(stream)
+            if (!websocketStream) {
+                return false;
+            }
+            websocketStream.start();
+        }
+        return true;
+    }
+
+    /**
+     * Unsubscribe from one, multiple or all streams
+     *
+     * @param {string[]|string} streams
+     */
+    unsubscribe(streams) {
+        let websocketClient = this.getWebsocketClient();
+        if (!streams) {
+            websocketClient.disconnect();
+            return;
+        }
+
+        if (typeof streams === "string") {
+            streams = [streams];
+        }
+
+        for (let stream of streams) {
+            let websocketStream = websocketClient.getStream(stream)
+            if (websocketStream) {
+                websocketStream.stop();
+            }
+        }
+        return true;
+    }
+
     /**
      * Map raw object to this instance
      *

package/src/Websocket/ConsoleStream.js

@@ -0,0 +1,33 @@
+const Stream = require("./Stream");
+
+class ConsoleStream extends Stream {
+    #ansiRegex = new RegExp('[\\u001B\\u009B][[\\]()#;?]*(?:(?:(?:[a-zA-Z\\d]*(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]*)*)?\\u0007)|(?:(?:\\d{1,4}(?:;\\d{0,4})*)?[\\dA-PR-TZcf-ntqry=><~]))', "g");
+    name = "console";
+    startData = {tail: 0};
+
+    onDataMessage(type, message) {
+        switch (type) {
+            case "line":
+                this.emitEvent("line", {rawLine: message.data, line: this.parseLine(message.data)});
+        }
+    }
+
+    parseReturns(str) {
+        str = str.replace(/^\r|\r$/, '');
+        let rIndex = str.lastIndexOf('\r');
+        if (rIndex !== -1) {
+            str = str.substr(rIndex + 1);
+        }
+        return str;
+    }
+
+    parseLine(line) {
+        return this.parseReturns(line).replace(this.#ansiRegex, '');
+    }
+
+    sendCommand(command) {
+        this.send("command", command);
+    }
+}
+
+module.exports = ConsoleStream;

package/src/Websocket/HeapStream.js

@@ -0,0 +1,8 @@
+const Stream = require("./Stream");
+
+class HeapStream extends Stream {
+    name = "heap";
+    startStatuses = [1];
+}
+
+module.exports = HeapStream;

package/src/Websocket/StatsStream.js

@@ -0,0 +1,8 @@
+const Stream = require("./Stream");
+
+class StatsStream extends Stream {
+    name = "stats";
+    startStatuses = [1];
+}
+
+module.exports = StatsStream;

package/src/Websocket/Stream.js

@@ -0,0 +1,163 @@
+const EventEmitter = require('events');
+
+class Stream extends EventEmitter {
+    /**
+     * @type {WebsocketClient}
+     */
+    #client;
+
+    /**
+     * @type {boolean}
+     */
+    #started = false;
+
+    /**
+     * @type {boolean}
+     */
+    #shouldStart = false;
+
+    /**
+     * @type {string}
+     */
+    name;
+
+    /**
+     * @type {{}}
+     */
+    startData;
+
+    /**
+     * @type {number[]}
+     */
+    startStatuses = [1, 2, 3, 4];
+
+    /**
+     * @param {WebsocketClient} client
+     */
+    constructor(client) {
+        super();
+        this.#client = client;
+        this.#client.on('status', this.onStatusChange.bind(this));
+        this.#client.on('ready', this.onStatusChange.bind(this));
+        this.#client.on('disconnected', this.onDisconnected.bind(this));
+        this.#client.on('close', this.onDisconnected.bind(this));
+    }
+
+    /**
+     * @param type
+     * @param data
+     */
+    send(type, data) {
+        this.#client.send(this.name, type, data);
+    }
+
+    /**
+     * Status change event
+     */
+    onStatusChange() {
+        this.tryToStart();
+        this.tryToStop();
+    }
+
+    /**
+     * Message event listener
+     *
+     * @param message
+     */
+    onMessage(message) {
+        switch (message.type) {
+            case "started":
+                this.emit("started");
+                this.#started = true;
+                break;
+            case "stopped":
+                this.emit("stopped");
+                this.#started = false;
+                break;
+            default:
+                this.onDataMessage(message.type, message);
+        }
+    }
+
+    onDataMessage(type, message) {
+        this.emitEvent(type, message.data);
+    }
+
+    onDisconnected() {
+        this.#started = false;
+    }
+
+    /**
+     * Double event emitter for generic or specific event handling
+     *
+     * @param type
+     * @param data
+     */
+    emitEvent(type, data) {
+        this.emit(type, data);
+        this.emit("event", {stream: this.name, type: type, data: data});
+    }
+
+    /**
+     * Start this stream
+     */
+    start(data) {
+        if (data) {
+            this.startData = data;
+        }
+        this.#shouldStart = true;
+        this.tryToStart();
+    }
+
+    /**
+     * Should/can this stream be started
+     *
+     * @return {boolean}
+     */
+    async shouldBeStarted() {
+        return this.#shouldStart && this.startStatuses.includes(await this.#client.getServerStatus());
+    }
+
+    /**
+     * Try to start if possible
+     *
+     * @return {boolean}
+     */
+    async tryToStart() {
+        if (this.#started || !this.#client.isReady() || !await this.shouldBeStarted()) {
+            return false;
+        }
+
+        this.send("start", this.startData);
+    }
+
+    /**
+     * Stop this stream
+     */
+    stop() {
+        this.#shouldStart = false;
+        this.tryToStop();
+        delete this.#client.removeStream(this.name);
+    }
+
+    /**
+     * Try to stop this stream if possible
+     *
+     * @return {boolean}
+     */
+    async tryToStop() {
+        if (!this.#started || await this.shouldBeStarted()) {
+            return false;
+        }
+        this.send("stop");
+    }
+
+    /**
+     * @return {boolean}
+     */
+    isStarted() {
+        return this.#started;
+    }
+}
+
+module.exports = Stream;

package/src/Websocket/TickStream.js

@@ -0,0 +1,16 @@
+const Stream = require("./Stream");
+
+class TickStream extends Stream {
+    name = "tick";
+    startStatuses = [1];
+
+    onDataMessage(type, message) {
+        switch(type) {
+            case "tick":
+                message.data.tps = Math.round(Math.min(1000 / message.data.averageTickTime, 20) * 10) / 10;
+                this.emitEvent("tick", message.data);
+        }
+    }
+}
+
+module.exports = TickStream;

package/src/Websocket/WebsocketClient.js

@@ -0,0 +1,269 @@
+const EventEmitter = require('events');
+const WebSocket = require('ws');
+
+const ConsoleStream = require("./ConsoleStream");
+const HeapStream = require("./HeapStream");
+const StatsStream = require("./StatsStream");
+const TickStream = require("./TickStream");
+
+/**
+ * Websocket client to connect to the websocket for this server
+ */
+class WebsocketClient extends EventEmitter {
+    /**
+     * @type {string}
+     */
+    protocol = "wss";
+
+    /**
+     * @type {Client}
+     * @private
+     */
+    #client;
+
+    /**
+     * @type {Server}
+     * @private
+     */
+    #server;
+
+    /**
+     * @type {WebSocket}
+     */
+    #websocket;
+
+    /**
+     * Automatically reconnect in case of a disconnect
+     *
+     * @type {boolean}
+     */
+    autoReconnect = true;
+
+    /**
+     * Time to wait to reconnect
+     *
+     * Only change this with caution. A time too low here can
+     * cause a spam in requests which can get your application
+     * rate limited or even blocked.
+     *
+     * @type {number}
+     */
+    reconnectTimeout = 3000;
+
+    #reconnectInterval;
+
+    /**
+     * @type {boolean}
+     */
+    #connected = false;
+
+    /**
+     * @type {boolean}
+     */
+    #shouldConnect = false;
+
+    /**
+     * @type {boolean}
+     */
+    #serverConnected = false;
+
+    /**
+     * @type {boolean}
+     */
+    #ready = false;
+
+    /**
+     * @type {{{string}: Stream}}
+     */
+    #streams = {};
+
+    #availableStreams = {
+        "console": ConsoleStream,
+        "heap": HeapStream,
+        "stats": StatsStream,
+        "tick": TickStream
+    };
+
+    /**
+     * @param {Server} server
+     */
+    constructor(server) {
+        super();
+        this.#server = server;
+        this.#client = server.getClient();
+        this.protocol = this.#client.protocol === "https" ? "wss" : "ws";
+        this.url = this.protocol + "://" + this.#client.host + this.#client.basePath + "servers/" + this.#server.id + "/websocket";
+    }
+
+    /**
+     * Connect to websocket
+     */
+    connect() {
+        this.#shouldConnect = true;
+        this.#websocket = new WebSocket(this.url, {headers: {authorization: "Bearer " + this.#client.getAPIToken()}});
+        this.#websocket.on('open', this.onOpen.bind(this));
+        this.#websocket.on('close', this.onClose.bind(this));
+        this.#websocket.on('error', this.onError.bind(this));
+        this.#websocket.on('message', this.onMessage.bind(this));
+        if (!this.streamRetryInterval) {
+            this.streamRetryInterval = setInterval(this.tryToStartStreams.bind(this), 15000);
+        }
+    }
+
+    /**
+     * Disconnect from the websocket and all streams
+     */
+    disconnect() {
+        this.#shouldConnect = false;
+        this.#websocket.close();
+        this.#streams = {};
+        clearInterval(this.#reconnectInterval);
+        clearInterval(this.streamRetryInterval);
+        this.streamRetryInterval = null;
+    }
+
+    onOpen() {
+        this.#connected = true;
+        clearInterval(this.#reconnectInterval);
+        this.emit('open');
+    }
+
+    onClose() {
+        this.emit('close');
+        this.#ready = false;
+        if (this.autoReconnect && this.#shouldConnect) {
+            this.#reconnectInterval = setInterval(this.connect.bind(this), this.reconnectTimeout);
+        } else {
+            this.#connected = false;
+        }
+    }
+
+    onError(error) {
+        this.emit('error', error);
+    }
+
+    onMessage(rawMessage) {
+        let message = JSON.parse(rawMessage);
+
+        // noinspection FallThroughInSwitchStatementJS
+        switch (message.type) {
+            case "keep-alive":
+                break;
+            case "ready":
+                this.#ready = true;
+                this.emit('ready');
+                break;
+            case "connected":
+                this.#serverConnected = true;
+                this.emit('connected');
+                break;
+            case "disconnected":
+                this.#serverConnected = false;
+                this.emit('disconnected');
+                if (this.autoReconnect) {
+                    setTimeout(this.tryToStartStreams.bind(this), this.reconnectTimeout);
+                }
+                break;
+            case "status":
+                if (message.stream === "status") {
+                    this.#server.setFromObject(message.data);
+                    this.emit('status', this.#server);
+                    break;
+                }
+            default:
+                if (message.stream && this.#streams[message.stream]) {
+                    this.#streams[message.stream].onMessage(message);
+                }
+        }
+
+    }
+
+    /**
+     * @return {boolean}
+     */
+    isConnected() {
+        return this.#connected;
+    }
+
+    /**
+     * @return {boolean}
+     */
+    isReady() {
+        return this.#ready;
+    }
+
+    /**
+     * @return {Server}
+     */
+    getServer() {
+        return this.#server;
+    }
+
+    /**
+     * @return {int|number}
+     */
+    async getServerStatus() {
+        if (!Number.isInteger(this.#server.status)) {
+            await this.#server.get();
+        }
+        return this.#server.status;
+    }
+
+    /**
+     * Get a stream by name
+     *
+     * @param {string} stream
+     * @return {boolean|Stream}
+     */
+    getStream(stream) {
+        if (!this.#availableStreams[stream]) {
+            return false;
+        }
+
+        if (this.#streams[stream]) {
+            return this.#streams[stream];
+        }
+
+        this.#streams[stream] = new this.#availableStreams[stream](this);
+        this.#streams[stream].on('event', (data) => this.emit('event', data));
+        return this.#streams[stream];
+    }
+
+    /**
+     * @param stream
+     * @return {boolean}
+     */
+    hasStream(stream) {
+        return !!this.#streams[stream];
+    }
+
+    tryToStartStreams() {
+        for (let stream of Object.keys(this.#streams)) {
+            this.#streams[stream].tryToStart();
+        }
+    }
+
+    removeStream(stream) {
+        delete this.#streams[stream];
+    }
+
+    /**
+     * @param stream
+     * @param type
+     * @param data
+     * @return {boolean}
+     */
+    send(stream, type, data) {
+        if (this.#websocket.readyState !== 1 || !this.isReady()) {
+            return false;
+        }
+
+        let message = {stream: stream, type: type};
+        if (typeof data !== "undefined") {
+            message.data = data;
+        }
+        this.#websocket.send(JSON.stringify(message));
+    }
+}
+
+module.exports = WebsocketClient;