wispjs 2.4.0 → 3.0.0

package/dist/wisp_socket/pool.js

@@ -1,4 +1,4 @@
-import { io } from "socket.io-client";
+import { WispWebSocket } from "./ws_adapter.js";
 const WISP_DEBUG = process.env.WISP_DEBUG === "true";
 /**
  * A single Worker within a {@link WebsocketPool}
@@ -9,17 +9,16 @@ const WISP_DEBUG = process.env.WISP_DEBUG === "true";
  */
 class PoolWorker {
     constructor(pool) {
+        this.intentionalDisconnect = false;
+        this.reconnectAttempts = 0;
+        this.maxReconnectAttempts = 3;
         this.pool = pool;
-        this.ready = false;
+        this.connected = false;
+        this.busy = false;
         this.done = false;
         this.idx = pool.workers.length;
         this.token = pool.token;
-        this.socket = io(pool.url, {
-            forceNew: true,
-            transports: ["websocket"],
-            addTrailingSlash: true,
-            autoConnect: false
-        });
+        this.url = pool.url;
         const logPrefix = `[Worker #${this.idx}]`;
         this.logger = {
             log: (...args) => console.log(logPrefix, args),
@@ -30,7 +29,22 @@ class PoolWorker {
                 console.debug(logPrefix, args);
             }
         };
-        this.connect().then(() => this.processWork()).catch(err => this.logger.error(err));
+        this.start();
+        this.processWork();
+    }
+    createSocket() {
+        this.socket = new WispWebSocket(this.url, {
+            origin: this.pool.origin
+        });
+    }
+    start() {
+        this.createSocket();
+        this.connect()
+            .then(() => this.logger.log("Connection established"))
+            .catch((err) => {
+            this.logger.error("Connection failed", err);
+            this.handleDisconnect("connection failure");
+        });
     }
     connect() {
         const socket = this.socket;
@@ -40,11 +54,10 @@ class PoolWorker {
         return new Promise((resolve, reject) => {
             const timeout = setTimeout(() => {
                 logger.error("Socket didn't connect in time");
-                reject("Connection Timeout");
+                reject(new Error("Connection Timeout"));
             }, 10000);
             socket.on("connect", () => {
-                logger.log("Connected to WebSocket");
-                logger.log("Emitting:", "auth", this.token);
+                logger.log("Connected to WebSocket, authenticating");
                 socket.emit("auth", this.token);
             });
             socket.on("error", (reason) => {
@@ -52,28 +65,65 @@ class PoolWorker {
             });
             socket.on("connect_error", (error) => {
                 logger.error(`WebSocket Connect error: ${error.toString()}`);
-                this.done = true;
                 clearTimeout(timeout);
-                reject(`Connection error: ${error.toString()}`);
+                reject(error);
             });
             socket.on("disconnect", (reason) => {
                 logger.log(`Disconnected from WebSocket: ${reason}`);
+                this.connected = false;
+                this.handleDisconnect(reason);
             });
-            socket.on("auth_success", () => {
+            socket.on("auth success", () => {
                 logger.log("Auth success");
-                this.ready = true;
+                this.reconnectAttempts = 0;
+                this.connected = true;
                 clearTimeout(timeout);
                 resolve();
             });
             socket.connect();
         });
     }
+    // Recovers from an unexpected disconnect by reconnecting with a freshly
+    // fetched token (the JWT is short-lived). After maxReconnectAttempts the
+    // worker is marked dead so the pool stops handing it work.
+    async handleDisconnect(reason) {
+        this.connected = false;
+        if (this.intentionalDisconnect || this.done) {
+            return;
+        }
+        if (this.reconnectAttempts >= this.maxReconnectAttempts) {
+            this.logger.error(`Giving up after ${this.reconnectAttempts} reconnect attempts (${reason})`);
+            this.done = true;
+            this.pool.onWorkerDone();
+            return;
+        }
+        this.reconnectAttempts++;
+        const backoff = Math.min(1000 * this.reconnectAttempts, 5000);
+        this.logger.log(`Reconnecting (attempt ${this.reconnectAttempts}/${this.maxReconnectAttempts}) in ${backoff}ms`);
+        await new Promise((resolve) => setTimeout(resolve, backoff));
+        if (this.intentionalDisconnect || this.done) {
+            return;
+        }
+        if (this.pool.refreshDetails) {
+            try {
+                const details = await this.pool.refreshDetails();
+                this.url = details.url;
+                this.token = details.token;
+            }
+            catch (e) {
+                this.logger.error("Failed to refresh websocket details for reconnect", e);
+            }
+        }
+        this.start();
+    }
     disconnect() {
-        this.ready = false;
-        return new Promise((resolve, reject) => {
+        this.intentionalDisconnect = true;
+        this.connected = false;
+        return new Promise((resolve) => {
             const timeout = setTimeout(() => {
                 this.logger.error("Socket didn't disconnect in time");
-                reject();
+                this.done = true;
+                resolve();
             }, 5000);
             this.socket.once("disconnect", () => {
                 this.done = true;
@@ -85,13 +135,13 @@ class PoolWorker {
     }
     async processWork() {
         while (!this.done) {
-            if (!this.ready) {
+            if (!this.connected || this.busy) {
                 await new Promise(resolve => setTimeout(resolve, 100));
                 continue;
             }
             const work = this.pool.getWork();
             if (work) {
-                this.ready = false;
+                this.busy = true;
                 try {
                     this.logger.debug("Running my work");
                     await work(this);
@@ -102,7 +152,7 @@ class PoolWorker {
                     this.logger.error(e);
                 }
                 finally {
-                    this.ready = true;
+                    this.busy = false;
                 }
             }
             else {
@@ -123,11 +173,15 @@ class PoolWorker {
  * @internal
  */
 export class WebsocketPool {
-    constructor(url, token) {
+    constructor(url, token, origin, refreshDetails) {
         const envMaxWorkers = process.env.WISP_MAX_WORKERS;
         this.maxWorkers = envMaxWorkers ? parseInt(envMaxWorkers) : 5;
+        const envAcquire = process.env.WISP_ACQUIRE_TIMEOUT;
+        this.acquireTimeout = envAcquire ? parseInt(envAcquire) : 60000;
         this.token = token;
         this.url = url;
+        this.origin = origin;
+        this.refreshDetails = refreshDetails;
         const logPrefix = "[Pool]";
         this.logger = {
             log: (...args) => console.log(logPrefix, args),
@@ -146,7 +200,22 @@ export class WebsocketPool {
         }
     }
     getWork() {
-        return this.queue.shift();
+        return this.queue.shift()?.task;
+    }
+    allWorkersDone() {
+        return this.workers.length > 0 && this.workers.every((worker) => worker.done);
+    }
+    // Called by a worker when it gives up permanently. If no workers remain,
+    // queued work can never run, so reject it instead of letting it hang.
+    onWorkerDone() {
+        if (!this.allWorkersDone()) {
+            return;
+        }
+        this.logger.error("All workers are dead - draining queued work");
+        const error = new Error("WebsocketPool has no live workers");
+        while (this.queue.length > 0) {
+            this.queue.shift()?.reject(error);
+        }
     }
     async disconnect() {
         this.logger.log("Disconnecting all workers...");
@@ -154,17 +223,47 @@ export class WebsocketPool {
         this.logger.log("All workers disconnected");
     }
     async run(work) {
-        return new Promise(async (resolve, reject) => {
-            this.queue.push(async (worker) => {
-                try {
-                    const result = await work(worker);
-                    resolve(result);
+        return new Promise((resolve, reject) => {
+            if (this.allWorkersDone()) {
+                reject(new Error("WebsocketPool has no live workers"));
+                return;
+            }
+            let settled = false;
+            const item = {
+                task: async (worker) => {
+                    if (settled) {
+                        return;
+                    }
+                    settled = true;
+                    clearTimeout(acquireTimer);
+                    try {
+                        const result = await work(worker);
+                        resolve(result);
+                    }
+                    catch (e) {
+                        worker.logger.error("Failed to run a job!");
+                        reject(e);
+                    }
+                },
+                reject: (reason) => {
+                    if (settled) {
+                        return;
+                    }
+                    settled = true;
+                    clearTimeout(acquireTimer);
+                    reject(reason);
                 }
-                catch (e) {
-                    worker.logger.error("Failed to run a job!");
-                    reject(e);
+            };
+            // Backstop so work can't sit in the queue forever if every worker
+            // is wedged. Worker death is handled separately by onWorkerDone.
+            const acquireTimer = setTimeout(() => {
+                const idx = this.queue.indexOf(item);
+                if (idx !== -1) {
+                    this.queue.splice(idx, 1);
                 }
-            });
+                item.reject(new Error(`Timed out waiting for an available worker after ${this.acquireTimeout}ms`));
+            }, this.acquireTimeout);
+            this.queue.push(item);
         });
     }
 }

package/dist/wisp_socket/ws_adapter.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Options for the {@link WispWebSocket} adapter
+ *
+ * @param origin The value to send as the `Origin` header during the upgrade
+ *
+ * @internal
+ */
+export interface WsAdapterOptions {
+    origin?: string;
+}
+/**
+ * A thin adapter that exposes a Socket.IO-like event API over a plain `ws`
+ * WebSocket.
+ *
+ * The new backend speaks a simple JSON envelope rather than the Socket.IO /
+ * Engine.IO framing:
+ *
+ * ```json
+ * { "event": "console output", "args": ["...line..."] }
+ * ```
+ *
+ * `args` is omitted entirely when an event carries no payload
+ * (e.g. `{ "event": "auth success" }`).
+ *
+ * This class translates between that envelope and the `.on/.once/.off/.emit`
+ * surface the rest of the codebase already uses, so the calling code barely
+ * changes.
+ *
+ * @remarks
+ * We *compose* an EventEmitter instead of extending one on purpose: extending
+ * it would mean overriding `emit()`, which EventEmitter also calls internally
+ * (e.g. the `newListener` event) — so every `.on()` would try to send a frame
+ * to the server. Composition keeps "emit to the wire" and "fire local
+ * listeners" cleanly separate.
+ *
+ * @internal
+ */
+export declare class WispWebSocket {
+    private url;
+    private origin?;
+    private ws?;
+    private emitter;
+    private outgoingListener?;
+    constructor(url: string, opts?: WsAdapterOptions);
+    /**
+     * Opens the underlying WebSocket and wires up frame translation.
+     */
+    connect(): this;
+    /**
+     * Sends an event to the server as a `{ event, args }` JSON frame.
+     *
+     * @remarks
+     * Unlike EventEmitter.emit, this does NOT fire local listeners — it writes
+     * to the socket. Incoming frames fire local listeners via the internal
+     * emitter.
+     */
+    emit(event: string, ...args: any[]): boolean;
+    on(event: string, listener: (...args: any[]) => void): this;
+    once(event: string, listener: (...args: any[]) => void): this;
+    /**
+     * Removes a specific listener, or — matching Socket.IO's behaviour — all
+     * listeners for an event when no listener is given.
+     */
+    off(event: string, listener?: (...args: any[]) => void): this;
+    removeAllListeners(event?: string): this;
+    /**
+     * Registers a callback invoked for every outgoing emit (parity with
+     * Socket.IO's `onAnyOutgoing`, used for logging).
+     */
+    onAnyOutgoing(listener: (...args: any[]) => void): this;
+    disconnect(): this;
+}

package/dist/wisp_socket/ws_adapter.js

@@ -0,0 +1,130 @@
+import WebSocket from "ws";
+import { EventEmitter } from "node:events";
+/**
+ * A thin adapter that exposes a Socket.IO-like event API over a plain `ws`
+ * WebSocket.
+ *
+ * The new backend speaks a simple JSON envelope rather than the Socket.IO /
+ * Engine.IO framing:
+ *
+ * ```json
+ * { "event": "console output", "args": ["...line..."] }
+ * ```
+ *
+ * `args` is omitted entirely when an event carries no payload
+ * (e.g. `{ "event": "auth success" }`).
+ *
+ * This class translates between that envelope and the `.on/.once/.off/.emit`
+ * surface the rest of the codebase already uses, so the calling code barely
+ * changes.
+ *
+ * @remarks
+ * We *compose* an EventEmitter instead of extending one on purpose: extending
+ * it would mean overriding `emit()`, which EventEmitter also calls internally
+ * (e.g. the `newListener` event) — so every `.on()` would try to send a frame
+ * to the server. Composition keeps "emit to the wire" and "fire local
+ * listeners" cleanly separate.
+ *
+ * @internal
+ */
+export class WispWebSocket {
+    constructor(url, opts = {}) {
+        this.emitter = new EventEmitter();
+        this.url = url;
+        this.origin = opts.origin;
+        // The pool registers a handful of listeners per worker; silence the
+        // default 10-listener warning.
+        this.emitter.setMaxListeners(0);
+    }
+    /**
+     * Opens the underlying WebSocket and wires up frame translation.
+     */
+    connect() {
+        const ws = new WebSocket(this.url, this.origin ? { origin: this.origin } : undefined);
+        this.ws = ws;
+        // Map ws lifecycle onto the Socket.IO-style events the pool listens for
+        ws.on("open", () => this.emitter.emit("connect"));
+        ws.on("close", (code, reason) => {
+            this.emitter.emit("disconnect", reason?.toString() || `code ${code}`);
+        });
+        ws.on("error", (err) => this.emitter.emit("connect_error", err));
+        ws.on("message", (data, isBinary) => {
+            if (isBinary)
+                return;
+            let frame;
+            try {
+                frame = JSON.parse(data.toString());
+            }
+            catch {
+                return; // ignore anything that isn't our JSON envelope
+            }
+            const event = frame.event;
+            if (!event)
+                return;
+            const args = frame.args ?? [];
+            // EventEmitter throws if "error" is emitted with no listener; guard it.
+            if (event === "error" && this.emitter.listenerCount("error") === 0) {
+                console.error("[ws] server error frame:", ...args);
+                return;
+            }
+            this.emitter.emit(event, ...args);
+        });
+        return this;
+    }
+    /**
+     * Sends an event to the server as a `{ event, args }` JSON frame.
+     *
+     * @remarks
+     * Unlike EventEmitter.emit, this does NOT fire local listeners — it writes
+     * to the socket. Incoming frames fire local listeners via the internal
+     * emitter.
+     */
+    emit(event, ...args) {
+        this.outgoingListener?.(event, ...args);
+        const frame = JSON.stringify(args.length ? { event, args } : { event });
+        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+            this.ws.send(frame);
+        }
+        else {
+            console.error(`[ws] dropped outgoing "${event}" — socket not open`);
+        }
+        return true;
+    }
+    on(event, listener) {
+        this.emitter.on(event, listener);
+        return this;
+    }
+    once(event, listener) {
+        this.emitter.once(event, listener);
+        return this;
+    }
+    /**
+     * Removes a specific listener, or — matching Socket.IO's behaviour — all
+     * listeners for an event when no listener is given.
+     */
+    off(event, listener) {
+        if (listener) {
+            this.emitter.off(event, listener);
+        }
+        else {
+            this.emitter.removeAllListeners(event);
+        }
+        return this;
+    }
+    removeAllListeners(event) {
+        this.emitter.removeAllListeners(event);
+        return this;
+    }
+    /**
+     * Registers a callback invoked for every outgoing emit (parity with
+     * Socket.IO's `onAnyOutgoing`, used for logging).
+     */
+    onAnyOutgoing(listener) {
+        this.outgoingListener = listener;
+        return this;
+    }
+    disconnect() {
+        this.ws?.close();
+        return this;
+    }
+}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "wispjs",
-  "version": "2.4.0",
+  "version": "3.0.0",
   "type": "module",
   "description": "A package for interacting with Wisp-based server panels",
   "main": "dist/wisp.js",
   "types": "dist/wisp.d.ts",
   "scripts": {
     "build": "tsc",
-    "build-docs": "typedoc wisp.ts wisp_api/index.ts wisp_socket/index.ts wisp_api/apis/*"
+    "build-docs": "typedoc wisp.ts wisp_api/index.ts wisp_socket/index.ts wisp_socket/git.ts wisp_socket/filesystem.ts wisp_api/apis/*"
   },
   "repository": {
     "type": "git",
@@ -20,11 +20,12 @@
   },
   "homepage": "https://github.com/CFC-Servers/WispJS#readme",
   "dependencies": {
-    "socket.io-client": "^4.7.2",
-    "strip-ansi": "^7.1.0"
+    "strip-ansi": "^7.1.0",
+    "ws": "^8.21.0"
   },
   "devDependencies": {
     "@types/node": "^20.5.4",
+    "@types/ws": "^8.18.1",
     "typedoc": "^0.25.4",
     "typescript": "^5.3.3"
   }

package/.github/workflows/release.yml

@@ -1,77 +0,0 @@
-name: Deploy
-
-on:
-  workflow_dispatch:
-    inputs:
-      version_tag:
-        description: "Version tag for the package"
-        required: true
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 18
-
-      - name: Update package version
-        run: |
-          version=${{ inputs.version_tag }}
-          npm version $version --no-git-tag-version
-
-      - name: Install packages
-        run: |
-          npm ci
-
-      - name: Build
-        run: |
-          npm run build
-
-      - name: Generate Docs
-        run: |
-          npm run build-docs
-          mv docs ../docs_wip
-
-      - name: Remove Non-distributables
-        run: |
-          rm .gitignore
-          rm tsconfig.json
-          rm wisp.ts
-          rm -rf wisp_api wisp_socket .github
-
-      - name: Publish
-        uses: JS-DevTools/npm-publish@v3
-        with:
-          token: ${{ secrets.NPM_PUBLISH_TOKEN }}
-
-      - name: Configure Git User
-        run: |
-          git config user.name github-actions
-          git config user.email github-actions@github.com
-
-      - name: Push package version change
-        run: |
-          git add package.json
-          git add package-lock.json
-          git commit -m "Update package.json version to: ${{ inputs.version_tag }}" && \
-            git push --force-with-lease origin main || \
-            echo "Version tag unchanaged"
-
-      - name: Push new tag
-        run: |
-          git tag "${{ inputs.version_tag }}"
-          git push --tags
-
-      - name: Publish Docs
-        run: |
-          # Delete everything except .git
-          find . -mindepth 1 -maxdepth 1 ! -name '.git' -exec rm -rf {} +
-
-          # Move the docs back and commit only them
-          mv ../docs_wip docs
-          git add .
-          git commit -m "Update Docs for version: ${{ inputs.version_tag }}"
-          git push --force origin HEAD:docs

package/tsconfig.json

@@ -1,19 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "ESNext",
-
-    "outDir": "./dist/",
-    "declaration": true,
-
-    "esModuleInterop": true,
-    "forceConsistentCasingInFileNames": true,
-
-    "strict": true,
-    "skipLibCheck": true,
-    "moduleResolution": "node"
-  },
-  "include": ["*.ts"],
-  "exclude": ["node_modules"]
-}
-

package/wisp.ts

@@ -1,43 +0,0 @@
-import { WispAPI } from "./wisp_api/index.js";
-import { WispSocket } from "./wisp_socket/index.js";
-
-export interface WispInterface {
-  socket: WispSocket;
-  api: WispAPI;
-  logger: any;
-}
-
-/**
- * The primary Wisp Interface, exposing interactions with both the HTTP and Websockets API
- *
- * @param domain The Domain of the Pterodactyl/Wisp panel (e.g. `my.gamepanel.gg`)
- * @param uuid The UUID of the server to reference in all API requests
- * @param token The panel API token to use for authorization
- * @param ghPAT The Github Personal Access Token used for Cloning/Pulling of private repositories. This may be omitted if you do not need to interact with private repositories
- *
- * @public
- */
-export class WispInterface {
-  constructor(domain: string, uuid: string, token: string, ghPAT?: string) {
-    this.logger = {
-      info: (msg: any) => {
-        console.log(msg);
-      },
-      error: (msg: string) => {
-        console.error(msg);
-      }
-    };
-
-    this.api = new WispAPI(domain, uuid, token, this.logger);
-    this.socket = new WispSocket(this.logger, this.api, ghPAT);
-  }
-
-  /**
-   * Manually disconnects from the Websocket connection(s)
-   *
-   * @public
-   */
-  async disconnect() {
-    await this.socket.disconnect();
-  }
-}