exaroton 1.7.0 → 1.8.0

package/.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+name: Node.js Package
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  publish-npm:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 16
+          registry-url: https://registry.npmjs.org/
+      - run: npm ci
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

package/README.md

@@ -218,6 +218,79 @@ try {
 }
 ```
 
+#### Files
+
+You can request information about files, download and upload files.
+
+##### Get a file object
+This just creates the file object but doesn't request any information or content
+```js
+let file = server.getFile("server.properties");
+```
+
+##### Get file information
+If a file doesn't exist you will get a 404 error.
+```js
+try {
+    await file.getInfo();
+    console.log(file);
+} catch (e) {
+    console.error(e.message);
+}
+```
+
+##### Get the content of a file / download a file
+```js
+try {
+    // get the content of the file in a variable
+    // large files will cause high memory usage
+    let content = await file.getContent();
+    console.log(content);
+    
+    // or download the file to a local file
+    await file.download("test.txt");
+    
+    // or download the file to a stream
+    let stream = await file.downloadToStream(createWriteStream("test.txt"));
+} catch (e) {
+    console.error(e.message);
+}
+```
+
+##### Change the content of a file / upload a file
+```js
+try {
+    // change the content of the file
+    await file.setContent("Hello world!");
+    
+    // or upload a local file
+    await file.upload("test.txt");
+    
+    // or upload from a stream
+    await file.uploadFromStream(createReadStream("test.txt"));
+} catch (e) {
+    console.error(e.message);
+}
+```
+
+##### Delete a file
+```js
+try {
+    await file.delete();
+} catch (e) {
+    console.error(e.message);
+}
+```
+
+##### Create a directory
+```js
+try {
+    await file.createAsDirectory();
+} 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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "exaroton",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "exaroton API client",
   "homepage": "https://exaroton.com",
   "main": "index.js",

package/src/Client.js

@@ -1,4 +1,5 @@
 const got = require('got');
+const fs = require("fs").promises;
 
 const Server = require('./Server/Server');
 const Account = require('./Account/Account');
@@ -29,7 +30,9 @@ class Client {
      *
      * @type {string}
      */
-    get baseURL() { return this.protocol + "://" + this.host + this.basePath }
+    get baseURL() {
+        return this.protocol + "://" + this.host + this.basePath
+    }
 
     /**
      * API token used for authentication
@@ -112,7 +115,7 @@ class Client {
             method: request.method,
             retry: 0,
             headers: headers,
-            responseType: "json"
+            responseType: request.responseType
         };
 
         if (request.hasBody()) {
@@ -121,22 +124,51 @@ class Client {
 
         let response;
         try {
-            response = await got(url, gotOptions);
+            if (request.hasOutputStream()) {
+                await this.streamResponse(url, gotOptions, request.getOutputStream());
+                return request.createResponse();
+            } else {
+                response = await got(url, gotOptions);
+            }
         } catch (e) {
+            if (request.outputPath !== null) {
+                try {
+                    await fs.unlink(request.outputPath);
+                } catch (e) {
+                    // ignore
+                }
+            }
             throw new RequestStatusError(e);
         }
 
-        if (response.body.success) {
+        if (!request.expectsJsonResponse() || response.body.success) {
             return request.createResponse(response.body);
         } else {
             throw new RequestBodyError(response);
         }
     }
 
+    /**
+     * @param {string} url
+     * @param {{}} gotOptions
+     * @param {stream.Writable} outputStream
+     * @return {Promise<unknown>}
+     */
+    streamResponse(url, gotOptions, outputStream) {
+        return new Promise((resolve, reject) => {
+            let stream = got.stream(url, gotOptions);
+            stream.pipe(outputStream);
+            stream.on("error", async (error) => {
+                reject(error);
+            });
+            stream.on("end", resolve);
+        });
+    }
+
     /**
      * Get a list of all servers
      *
-     * @return {Response}
+     * @return {Promise<Server[]>}
      * @throws {RequestError}
      */
     async getServers() {

package/src/Request/Request.js

@@ -1,4 +1,6 @@
 const FormData = require('form-data');
+const {createReadStream} = require('fs');
+const {createWriteStream} = require("fs");
 
 const Response = require('../Response/Response');
 
@@ -32,7 +34,7 @@ class Request {
     /**
      * Post body data
      *
-     * @type {null|{}}
+     * @type {null|{}|string}
      */
     data = null;
 
@@ -43,6 +45,43 @@ class Request {
      */
     responseClass = Response;
 
+    /**
+     * Response type (text|json|buffer)
+     *
+     * https://github.com/sindresorhus/got/blob/main/documentation/2-options.md#responsetype
+     *
+     * @type {string}
+     */
+    responseType = "json";
+
+    /**
+     * Optional path to write the response body to
+     *
+     * @type {string|null}
+     */
+    outputPath = null;
+
+    /**
+     * Optional stream to stream the response body to
+     *
+     * @type {stream.Writable|null}
+     */
+    outputStream = null;
+
+    /**
+     * Optional path to read the request body from
+     *
+     * @type {string|null}
+     */
+    inputPath = null;
+
+    /**
+     * Optional stream to read the request body from
+     *
+     * @type {stream.Readable|null}
+     */
+    inputStream = null;
+
     /**
      * Client that has executed this request
      *
@@ -93,15 +132,23 @@ class Request {
      * @return {boolean}
      */
     hasBody() {
-        return ["POST", "PUT", "DELETE"].includes(this.method) && this.data !== null;
+        return ["POST", "PUT", "DELETE"].includes(this.method) && (this.data !== null || this.inputPath !== null || this.inputStream !== null);
     }
 
     /**
      * Get body for request
      *
-     * @return {FormData|string}
+     * @return {FormData|string|ReadStream}
      */
     getBody() {
+        if (this.hasInputStream()) {
+            return this.getInputStream();
+        }
+
+        if (typeof this.data === "string") {
+            return this.data;
+        }
+
         let body = new FormData();
         for (let key in this.data) {
             if (!this.data.hasOwnProperty(key)) {
@@ -121,14 +168,116 @@ class Request {
     /**
      * Create a response object for this request
      *
-     * @param {{}} body
+     * @param {{}|string|null} body
      * @return {Response}
      */
-    createResponse(body) {
+    createResponse(body = null) {
         let response = new (this.responseClass)(this);
         response.setBody(body);
         return response;
     }
+
+    /**
+     * @return {boolean}
+     */
+    expectsJsonResponse() {
+        return this.responseType === "json";
+    }
+
+    /**
+     * @return {null|stream.Writable}
+     */
+    getOutputStream() {
+        if (this.outputStream !== null) {
+            return this.outputStream;
+        }
+        if (this.outputPath !== null) {
+            return createWriteStream(this.outputPath);
+        }
+        return null;
+    }
+
+    /**
+     * @return {boolean}
+     */
+    hasOutputStream() {
+        return this.outputStream !== null || this.outputPath !== null;
+    }
+
+    /**
+     * @return {null|stream.Readable}
+     */
+    getInputStream() {
+        if (this.inputStream !== null) {
+            return this.inputStream;
+        }
+        if (this.inputPath !== null) {
+            return createReadStream(this.inputPath);
+        }
+        return null;
+    }
+
+    /**
+     * @return {boolean}
+     */
+    hasInputStream() {
+        return this.inputStream !== null || this.inputPath !== null;
+    }
+
+    /**
+     * Set the data to put as string
+     *
+     * @param {string|{}} data
+     * @return {this}
+     */
+    setData(data) {
+        this.data = data;
+        return this;
+    }
+
+    /**
+     * Set a file as input file for the request body
+     *
+     * @param {string} inputPath
+     * @return {this}
+     */
+    setInputPath(inputPath) {
+        this.inputPath = inputPath;
+        return this;
+    }
+
+    /**
+     * Set a file as output file for the response body
+     *
+     * @param {string} outputPath
+     * @return {this}
+     */
+    setOutputPath(outputPath) {
+        this.outputPath = outputPath;
+        return this;
+    }
+
+    /**
+     * Set a stream as input stream for the request body
+     *
+     * @param {stream.Readable} inputStream
+     * @return {this}
+     */
+    setInputStream(inputStream) {
+        this.inputStream = inputStream;
+        return this;
+    }
+
+    /**
+     * Set a stream as output stream for the response body
+     *
+     * @param {stream.Writable} outputStream
+     * @return {this}
+     */
+    setOutputStream(outputStream) {
+        this.outputStream = outputStream;
+        return this;
+    }
 }
 
 module.exports = Request;

package/src/Request/Server/Files/CreateDirectoryRequest.js

@@ -0,0 +1,9 @@
+const PutFileDataRequest = require("./PutFileDataRequest");
+
+class CreateDirectoryRequest extends PutFileDataRequest {
+    headers = {
+        "Content-Type": "inode/directory"
+    }
+}
+
+module.exports = CreateDirectoryRequest;

package/src/Request/Server/Files/DeleteFileDataRequest.js

@@ -0,0 +1,7 @@
+const FileDataRequest = require("./FileDataRequest");
+
+class DeleteFileDataRequest extends FileDataRequest {
+    method = "DELETE";
+}
+
+module.exports = DeleteFileDataRequest;

package/src/Request/Server/Files/FileDataRequest.js

@@ -0,0 +1,7 @@
+const FileRequest = require("./FileRequest");
+
+class FileDataRequest extends FileRequest {
+    endpoint = "servers/{id}/files/data/{path}";
+}
+
+module.exports = FileDataRequest;

package/src/Request/Server/Files/FileRequest.js

@@ -0,0 +1,26 @@
+const ServerRequest = require('../ServerRequest');
+
+class FileRequest extends ServerRequest {
+    /**
+     * FileRequest constructor
+     *
+     * @param {string} id
+     * @param {string} path
+     */
+    constructor(id, path) {
+        super(id);
+        this.setPath(path);
+    }
+
+    /**
+     * Set the path parameter and url encode all characters except slashes
+     *
+     * @return {this}
+     */
+    setPath(path) {
+        this.setParameter("path", path.replace(/[^\/]+/g, encodeURIComponent));
+        return this;
+    }
+}
+
+module.exports = FileRequest;

package/src/Request/Server/Files/GetFileDataRequest.js

@@ -0,0 +1,7 @@
+const FileDataRequest = require("./FileDataRequest");
+
+class GetFileDataRequest extends FileDataRequest {
+    responseType = "text";
+}
+
+module.exports = GetFileDataRequest;

package/src/Request/Server/Files/GetFileInformationRequest.js

@@ -0,0 +1,7 @@
+const FileRequest = require('./FileRequest');
+
+class GetFileInformationRequest extends FileRequest {
+    endpoint = "servers/{id}/files/info/{path}";
+}
+
+module.exports = GetFileInformationRequest;

package/src/Request/Server/Files/PutFileDataRequest.js

@@ -0,0 +1,7 @@
+const FileDataRequest = require("./FileDataRequest");
+
+class PutFileDataRequest extends FileDataRequest {
+    method = "PUT";
+}
+
+module.exports = PutFileDataRequest;

package/src/Response/Response.js

@@ -7,7 +7,7 @@ class Response {
     /**
      * (raw/parsed) response body
      *
-     * @type {{}}
+     * @type {{}|string}
      */
     body;
 
@@ -27,13 +27,21 @@ class Response {
      * @return {*|null}
      */
     getData() {
+        if (typeof this.body === "undefined" || this.body === null) {
+            return null;
+        }
+
+        if (typeof this.body === "string") {
+            return this.body;
+        }
+
         return typeof this.body.data !== "undefined" ? this.body.data : null;
     }
 
     /**
      * Set the body to this.body and maybe parse content
      *
-     * @param {{}} body
+     * @param {{}|string} body
      */
     setBody(body) {
         this.body = body;

package/src/Server/File.js

@@ -0,0 +1,256 @@
+const GetFileInformationRequest = require("../Request/Server/Files/GetFileInformationRequest");
+const GetFileDataRequest = require("../Request/Server/Files/GetFileDataRequest");
+const PutFileDataRequest = require("../Request/Server/Files/PutFileDataRequest");
+const DeleteFileDataRequest = require("../Request/Server/Files/DeleteFileDataRequest");
+const CreateDirectoryRequest = require("../Request/Server/Files/CreateDirectoryRequest");
+
+class File {
+    /**
+     * File path relative to server root
+     *
+     * @type {string}
+     */
+    path;
+
+    /**
+     * File name
+     *
+     * @type {string}
+     */
+    name;
+
+    /**
+     * @type {boolean}
+     */
+    isTextFile;
+
+    /**
+     * @type {boolean}
+     */
+    isConfigFile;
+
+    /**
+     * @type {boolean}
+     */
+    isDirectory;
+
+    /**
+     * @type {boolean}
+     */
+    isLog;
+
+    /**
+     * @type {boolean}
+     */
+    isReadable;
+
+    /**
+     * @type {boolean}
+     */
+    isWritable;
+
+    /**
+     * @type {number}
+     */
+    size;
+
+    /**
+     * @type {[File]|null}
+     */
+    children = null;
+
+    /**
+     * @type {{Server}}
+     */
+    #server;
+
+    /**
+     * @type {{Client}}
+     */
+    #client;
+
+    /**
+     * @param {string|null} path
+     */
+    constructor(path = null) {
+        if (path) {
+            this.setPath(path);
+        }
+    }
+
+    /**
+     * @param {string} path
+     */
+    setPath(path) {
+        if (path.startsWith("/")) {
+            path = path.substring(1);
+        }
+        this.path = path;
+    }
+
+    /**
+     * Apply data from the API response
+     *
+     * @param {object} object
+     * @return {File}
+     */
+    applyData(object) {
+        if (typeof object.path !== "undefined") {
+            this.setPath(object.path);
+        }
+        this.name = typeof object.name !== "undefined" ? object.name : null;
+        this.isTextFile = typeof object.isTextFile !== "undefined" ? object.isTextFile : null;
+        this.isConfigFile = typeof object.isConfigFile !== "undefined" ? object.isConfigFile : null;
+        this.isDirectory = typeof object.isDirectory !== "undefined" ? object.isDirectory : null;
+        this.isLog = typeof object.isLog !== "undefined" ? object.isLog : null;
+        this.isReadable = typeof object.isReadable !== "undefined" ? object.isReadable : null;
+        this.isWritable = typeof object.isWritable !== "undefined" ? object.isWritable : null;
+        this.size = typeof object.size !== "undefined" ? object.size : null;
+        this.children = Array.isArray(object.children) ? object.children.map((child) => new File().applyData(child).setServer(this.#server).setClient(this.#client)) : null;
+        return this;
+    }
+
+    /**
+     * Set the server
+     *
+     * @param server
+     * @returns {this}
+     */
+    setServer(server) {
+        this.#server = server;
+        if (Array.isArray(this.children)) {
+            for (let child of this.children) {
+                child.setServer(server);
+            }
+        }
+        return this;
+    }
+
+    /**
+     * Set the API client
+     *
+     * @param client
+     * @returns {this}
+     */
+    setClient(client) {
+        this.#client = client;
+        if (Array.isArray(this.children)) {
+            for (let child of this.children) {
+                child.setClient(client);
+            }
+        }
+        return this;
+    }
+
+    /**
+     * Get file information from the API
+     *
+     * @returns {Promise<File>}
+     */
+    async getInfo() {
+        const response = await this.#client.request(new GetFileInformationRequest(this.#server.id, this.path));
+        this.applyData(response.getData());
+        return this;
+    }
+
+    /**
+     * Get the data/content of a file
+     *
+     * If you want to download the file to a local file use File.download() instead
+     *
+     * @return {Promise<string>}
+     */
+    async getContent() {
+        const response = await this.#client.request(new GetFileDataRequest(this.#server.id, this.path));
+        return response.getData();
+    }
+
+    /**
+     * Download the data/content of a file to a local file
+     *
+     * If you want to use the content of the file directly use File.getContent() instead
+     *
+     * @param {string} outputPath
+     * @return {Promise<Response>}
+     */
+    async download(outputPath) {
+        return await this.#client.request(new GetFileDataRequest(this.#server.id, this.path).setOutputPath(outputPath));
+    }
+
+    /**
+     * Download the data/content of a file into a writable stream
+     *
+     * @param {stream.Writable} outputStream
+     * @return {Promise<Response>}
+     */
+    async downloadToStream(outputStream) {
+        return await this.#client.request(new GetFileDataRequest(this.#server.id, this.path).setOutputStream(outputStream));
+    }
+
+    /**
+     * Put the content of a file
+     *
+     * If you want to upload a local file use File.upload() instead
+     *
+     * @param {string} content
+     * @return {Promise<Response>}
+     */
+    async putContent(content) {
+        return await this.#client.request(new PutFileDataRequest(this.#server.id, this.path).setData(content));
+    }
+
+    /**
+     * Upload a local file
+     *
+     * If you want to upload the content of the file directly as a string use File.putContent() instead
+     *
+     * @param {string} inputPath
+     * @return {Promise<Response>}
+     */
+    async upload(inputPath) {
+        return await this.#client.request(new PutFileDataRequest(this.#server.id, this.path).setInputPath(inputPath));
+    }
+
+    /**
+     * Upload from a readable stream
+     *
+     * @param {stream.Readable} inputStream
+     * @return {Promise<Response>}
+     */
+    async uploadFromStream(inputStream) {
+        return this.#client.request(new PutFileDataRequest(this.#server.id, this.path).setInputStream(inputStream));
+    }
+
+    /**
+     * Delete the file
+     *
+     * @return {Promise<Response>}
+     */
+    async delete() {
+        return await this.#client.request(new DeleteFileDataRequest(this.#server.id, this.path));
+    }
+
+    /**
+     * Create a directory
+     *
+     * @return {Promise<Response>}
+     */
+    async createAsDirectory() {
+        return await this.#client.request(new CreateDirectoryRequest(this.#server.id, this.path));
+    }
+
+    /**
+     * Get the children of a directory
+     *
+     * @return {Promise<[File]|null>}
+     */
+    async getChildren() {
+        if (this.children === null && this.isDirectory) {
+            await this.getInfo();
+        }
+
+        return this.children;
+    }
+}
+
+module.exports = File;

package/src/Server/Server.js

@@ -5,6 +5,7 @@ const Software = require('./Software');
 const Players = require('./Players');
 const ServerStatus = require('./ServerStatus');
 const PlayerList = require('./PlayerList');
+const File = require('./File');
 const GetServerRequest = require('../Request/Server/GetServerRequest');
 const StartServerRequest = require('../Request/Server/StartServerRequest');
 const StopServerRequest = require('../Request/Server/StopServerRequest');
@@ -306,6 +307,19 @@ class Server extends EventEmitter {
         return this.#playerLists[name];
     }
 
+    /**
+     * Get a file object for a server file
+     *
+     * This doesn't request file info or content yet.
+     * Use the File.getInfo() and File.getContent() functions for that
+     *
+     * @param {string} path The path of the file relative to the server root
+     * @return {File}
+     */
+    getFile(path) {
+        return new File(path).setServer(this).setClient(this.#client);
+    }
+
     /**
      * Check if the server has one or one of multiple status codes
      *
@@ -344,7 +358,7 @@ class Server extends EventEmitter {
      * Subscribe to one or multiple streams
      *
      * @return {boolean}
-     * @param {string[]|string} streams
+     * @param {string[]|string} [streams]
      */
     subscribe(streams) {
         let websocketClient = this.getWebsocketClient();
@@ -372,7 +386,7 @@ class Server extends EventEmitter {
     /**
      * Unsubscribe from one, multiple or all streams
      *
-     * @param {string[]|string} streams
+     * @param {string[]|string} [streams]
      */
     unsubscribe(streams) {
         let websocketClient = this.getWebsocketClient();
@@ -421,6 +435,28 @@ class Server extends EventEmitter {
         }
         return this;
     }
+
+    /**
+     * Only return intended public fields for JSON serialization
+     *
+     * Otherwise, fields inherited from EventEmitter would be serialized as well
+     *
+     * @returns {{}}
+     */
+    toJSON() {
+        return {
+            id: this.id,
+            name: this.name,
+            address: this.address,
+            motd: this.motd,
+            status: this.status,
+            host: this.host,
+            port: this.port,
+            shared: this.shared,
+            software: this.software,
+            players: this.players
+        }
+    }
 }
 
 module.exports = Server;