wispjs 2.4.0 → 3.0.0

package/dist/wisp_socket/index.js

@@ -1,5 +1,7 @@
 import stripAnsi from 'strip-ansi';
 import { WebsocketPool } from "./pool.js";
+import { GitSocket } from "./git.js";
+import { FilesystemSocket } from "./filesystem.js";
 /**
  * The primary interface to the Websocket API
  *
@@ -11,6 +13,8 @@ export class WispSocket {
         this.api = api;
         this.ghToken = ghToken;
         this.consoleCallbacks = [];
+        this.Git = new GitSocket(this);
+        this.Filesystem = new FilesystemSocket(this);
     }
     /**
      * Sets a callback to run on the Websocket Info before saving the details.
@@ -43,7 +47,16 @@ export class WispSocket {
         if (!this.url || !this.token) {
             throw new Error("Attempted to create a pool without a URL or token");
         }
-        this.pool = new WebsocketPool(this.url, this.token);
+        // Provider used by the pool to refresh the (short-lived) token when a
+        // worker needs to reconnect.
+        const refreshDetails = async () => {
+            await this.setDetails();
+            return { url: this.url, token: this.token };
+        };
+        // The Origin header is the panel the connection originates from, which
+        // is always the API domain.
+        const origin = `https://${this.api.domain}`;
+        this.pool = new WebsocketPool(this.url, this.token, origin, refreshDetails);
     }
     /**
      * Requests and saves the Websocket details from the API
@@ -58,7 +71,7 @@ export class WispSocket {
             }
             this.url = websocketInfo.url;
             this.token = websocketInfo.token;
-            this.logger.info("Got Websocket Details.", this.url, this.token);
+            this.logger.info(`Got Websocket Details. ${this.url} - ${this.token}`);
         }
         catch (e) {
             this.logger.error(`Failed to get websocket details: ${e}`);
@@ -87,178 +100,112 @@ export class WispSocket {
         }
     }
     /**
-     * Searches all file contents for the given query
+     * Runs a job on an available pool worker, handing it the worker's socket
+     * and logger. Used for event-based flows (e.g. file search) that don't fit
+     * the {@link request} request/response protocol.
      *
-     * @param query The query string to search for
-     * @param timeout How long to wait (in ms) for results before timing out
+     * @param work The job to run; receives the worker and returns a Promise
      *
-     * @public
+     * @internal
      */
-    async filesearch(query, timeout = 10000) {
-        this.logger.info("Running filesearch with: ", query);
+    async runWorker(work) {
         await this.verifyPool();
-        return await this.pool.run((worker) => {
-            const socket = worker.socket;
-            const logger = worker.logger;
-            logger.log("Running filesearch:", query);
-            return new Promise((resolve, reject) => {
-                const timeoutObj = setTimeout(() => {
-                    socket.off("filesearch-results");
-                    logger.error("Rejected filesearch: 'Timeout'");
-                    reject();
-                }, timeout);
-                socket.once("filesearch-results", (data) => {
-                    clearTimeout(timeoutObj);
-                    resolve(data);
-                });
-                socket.emit("filesearch-start", query);
-            });
-        });
+        return await this.pool.run(work);
     }
     /**
-     * Performs a git pull operation on the given directory
-     *
-     * @param dir The full directory path to perform a pull on
-     * @param timeout In milliseconds, how long to wait before timing out
+     * Generates a short, unique request id for {@link request} correlation.
      *
-     * @public
+     * @internal
      */
-    async gitPull(dir, useAuth = false, timeout = 10000) {
-        await this.verifyPool();
-        const pullResult = await this.pool.run((worker) => {
-            const socket = worker.socket;
-            const logger = worker.logger;
-            logger.log("Running gitPull:", dir);
-            return new Promise((resolve, reject) => {
-                let isPrivate = false;
-                let finished;
-                const timeoutObj = setTimeout(() => {
-                    logger.error("Rejected gitPull: 'Timeout'");
-                    finished(false, "Timeout");
-                }, timeout);
-                finished = (success, output) => {
-                    socket.removeAllListeners("git-pull");
-                    socket.removeAllListeners("git-error");
-                    socket.removeAllListeners("git-success");
-                    const result = {
-                        output: output,
-                        isPrivate: isPrivate
-                    };
-                    if (success) {
-                        resolve(result);
-                    }
-                    else {
-                        logger.error("Rejected gitPull:", dir, output);
-                        reject(output);
-                    }
-                    clearTimeout(timeoutObj);
-                };
-                const sendRequest = (includeAuth = false) => {
-                    const data = { dir: dir };
-                    if (includeAuth) {
-                        if (!this.ghToken) {
-                            logger.error("No GitHub token set, can't authenticate");
-                            return finished(false, "Authentication is required, but no GitHub token was set. Can't pull!");
-                        }
-                        isPrivate = true;
-                        data.authkey = this.ghToken;
-                    }
-                    socket.emit("git-pull", data);
-                };
-                socket.once("git-pull", (data) => {
-                    logger.log(`Updating ${data}`);
-                });
-                socket.once("git-success", (commit) => {
-                    logger.log(`Addon updated to ${commit}`);
-                    if (!commit) {
-                        logger.log("No commit given!");
-                    }
-                    finished(true, commit || "");
-                });
-                socket.on("git-error", (message) => {
-                    if (message === "Remote authentication required but no callback set") {
-                        logger.log(`Remote authentication required, trying again with authkey: ${dir}`);
-                        sendRequest(true);
-                    }
-                    else {
-                        logger.log(`Error updating addon: ${message}`);
-                        finished(false, message);
-                    }
-                });
-                sendRequest(useAuth);
-            });
-        });
-        return pullResult;
+    generateReqId() {
+        return Math.random().toString(36).slice(2, 14);
     }
     /**
-     * Clones a new Repo to the given directory
+     * Issues a correlated `fs:request` to the backend and awaits its outcome.
+     *
+     * This is the low-level entry point for the git/filesystem protocol. The
+     * client emits `fs:request` with a JSON-string payload (`{ req, op, ...params }`),
+     * and the backend replies with one of three events, all correlated by `req`
+     * and all carrying a JSON-string `args[0]`:
+     *
+     *   - `fs:result`   — success; resolves with the parsed `data`
+     *   - `fs:error`    — failure; rejects with an {@link FsError} (plus collected `output`)
+     *   - `fs:progress` — streaming stdout/stderr/progress lines (collected for error context)
+     *
+     * Typed convenience wrappers live on {@link GitSocket} ({@link WispSocket.Git})
+     * and {@link FilesystemSocket} ({@link WispSocket.Filesystem}); call this
+     * directly for ops that don't have a typed wrapper yet.
+     *
+     * @example
+     * ```js
+     * const status = await wisp.socket.request("git-status", { directory: "/garrysmod/addons/acf-3" })
+     * ```
      *
-     * @param url The HTTPS URL of the repository
-     * @param dir The full path of the directory to clone the repository to
-     * @param branch The branch of the repository to clone
-     * @param timeout In milliseconds, how long to wait before timing out
+     * @param op The operation name (e.g. `git-pull`, `list`)
+     * @param params Additional payload fields merged into the request (e.g. `{ directory }`)
+     * @param timeout In milliseconds, how long to wait for the result
      *
      * @public
      */
-    async gitClone(url, dir, branch, timeout = 20000) {
+    async request(op, params = {}, timeout = 10000) {
         await this.verifyPool();
         return await this.pool.run((worker) => {
             const socket = worker.socket;
             const logger = worker.logger;
-            logger.log("Running gitClone:", url, dir, branch);
+            const req = this.generateReqId();
+            logger.log(`Running fsRequest: ${op}`, params);
             return new Promise((resolve, reject) => {
-                let isPrivate = false;
-                let finished;
-                const timeoutObj = setTimeout(() => {
-                    logger.error("Rejected gitClone: 'Timeout'");
-                    finished(false, "Timeout");
-                }, timeout);
-                finished = (success, message) => {
-                    socket.removeAllListeners("git-clone");
-                    socket.removeAllListeners("git-error");
-                    socket.removeAllListeners("git-success");
-                    if (success) {
-                        const result = {
-                            isPrivate: isPrivate
-                        };
-                        resolve(result);
+                const progress = [];
+                let resultHandler;
+                let errorHandler;
+                let progressHandler;
+                const parse = (raw) => {
+                    try {
+                        return JSON.parse(raw);
                     }
-                    else {
-                        logger.error("Rejected gitClone:", url, dir, branch, message);
-                        reject(message);
+                    catch {
+                        logger.error(`Failed to parse fs event for ${op}`, raw);
+                        return undefined;
                     }
+                };
+                const cleanup = () => {
+                    socket.off("fs:result", resultHandler);
+                    socket.off("fs:error", errorHandler);
+                    socket.off("fs:progress", progressHandler);
                     clearTimeout(timeoutObj);
                 };
-                const sendRequest = (includeAuth = false) => {
-                    const data = { dir: dir, url: url, branch: branch };
-                    if (includeAuth) {
-                        if (!this.ghToken) {
-                            logger.error("No GitHub token set, can't authenticate");
-                            return finished(false, "Authentication is required, but no GitHub token was set. Can't clone!");
-                        }
-                        isPrivate = true;
-                        data.authkey = this.ghToken;
-                    }
-                    socket.emit("git-clone", data);
+                const timeoutObj = setTimeout(() => {
+                    cleanup();
+                    logger.error(`fsRequest timed out: ${op} (${req})`);
+                    reject(new Error(`fsRequest timed out: ${op}`));
+                }, timeout);
+                progressHandler = (raw) => {
+                    const p = parse(raw);
+                    if (!p || p.req !== req)
+                        return;
+                    const line = p.line ?? "";
+                    progress.push(line);
+                    logger.debug(`[${op}] ${p.kind}: ${line}`);
                 };
-                socket.once("git-clone", (data) => {
-                    logger.log(`Cloning ${data}`);
-                });
-                socket.once("git-success", () => {
-                    logger.log("Project successfully cloned");
-                    finished(true);
-                });
-                socket.on("git-error", (message) => {
-                    if (message === "Remote authentication required but no callback set") {
-                        logger.log(`Remote authentication required, trying again with authkey: ${dir}`);
-                        sendRequest(true);
-                    }
-                    else {
-                        logger.log("Error cloning repo:", url, dir, branch, message);
-                        finished(false, message);
-                    }
-                });
-                sendRequest();
+                resultHandler = (raw) => {
+                    const p = parse(raw);
+                    if (!p || p.req !== req)
+                        return;
+                    cleanup();
+                    resolve(p.data);
+                };
+                errorHandler = (raw) => {
+                    const p = parse(raw);
+                    if (!p || p.req !== req)
+                        return;
+                    cleanup();
+                    logger.error(`fsRequest error: ${op} - ${p.code}: ${p.message}`);
+                    reject({ ...p, output: progress.join("\n") });
+                };
+                socket.on("fs:result", resultHandler);
+                socket.on("fs:error", errorHandler);
+                socket.on("fs:progress", progressHandler);
+                socket.emit("fs:request", JSON.stringify({ req, op, ...params }));
             });
         });
     }
@@ -273,8 +220,7 @@ export class WispSocket {
                 const logger = worker.logger;
                 logger.log("Running setupConsoleListener");
                 return new Promise((resolve) => {
-                    worker.socket.on("console", (data) => {
-                        const line = data.line;
+                    worker.socket.on("console output", (line) => {
                         if (this.consoleCallbacks.length == 0) {
                             return resolve();
                         }
@@ -363,17 +309,16 @@ export class WispSocket {
                 let callback;
                 const timeoutObj = setTimeout(() => {
                     logger.error(`Command timed out current output: '${output}'`);
-                    socket.off("console", callback);
+                    socket.off("console output", callback);
                     logger.log("Rejected sendCommandNonce 'Timeout'", nonce, command);
                     reject("Timeout");
                 }, timeout);
-                callback = (data) => {
-                    const line = data.line;
+                callback = (line) => {
                     const clean = stripAnsi(line);
                     if (clean.startsWith(nonce)) {
                         const message = clean.slice(nonce.length);
                         if (message === "Done.") {
-                            socket.off("console", callback);
+                            socket.off("console output", callback);
                             clearTimeout(timeoutObj);
                             resolve(output);
                         }
@@ -383,7 +328,7 @@ export class WispSocket {
                         }
                     }
                 };
-                socket.on("console", callback);
+                socket.on("console output", callback);
                 socket.emit("send command", command);
             });
         });

package/dist/wisp_socket/pool.d.ts

@@ -1,9 +1,19 @@
-import { Socket } from "socket.io-client";
-type Logger = {
+import { WispWebSocket } from "./ws_adapter.js";
+export type Logger = {
     log(...args: any[]): void;
     error(...args: any[]): void;
     debug(...args: any[]): void;
 };
+/**
+ * The minimal worker surface handed to a job run via {@link WispSocket.runWorker}:
+ * the connected socket and a prefixed logger.
+ *
+ * @internal
+ */
+export interface SocketWorker {
+    socket: WispWebSocket;
+    logger: Logger;
+}
 /**
  * The struct used to define the events that can be sent from the server to the client
  *
@@ -11,13 +21,14 @@ type Logger = {
  */
 export interface ServerToClientEvents {
     "error": (message: string) => void;
-    "auth_success": (message: string) => void;
-    "filesearch-results": (data: FilesearchResults) => void;
-    "git-error": (data: string) => void;
-    "git-success": (message?: string) => void;
-    "git-clone": (data: GitCloneData) => void;
-    "git-pull": (data: GitPullData) => void;
-    "console": (message: ConsoleMessage) => void;
+    "auth success": () => void;
+    "console output": (line: string) => void;
+    "status": (state: string) => void;
+    "stats": (statsJson: string) => void;
+    "filesearch results": (json: string) => void;
+    "fs:result": (json: string) => void;
+    "fs:error": (json: string) => void;
+    "fs:progress": (json: string) => void;
     "initial status": (message: any) => void;
 }
 /**
@@ -27,72 +38,150 @@ export interface ServerToClientEvents {
  */
 export interface ClientToServerEvents {
     "auth": (token: string) => void;
-    "filesearch-start": (query: string) => void;
-    "git-clone": (data: GitCloneData) => void;
-    "git-pull": (data: GitPullData) => void;
+    "filesearch start": (json: string) => void;
+    "fs:request": (json: string) => void;
     "send command": (command: string) => void;
 }
 /**
- * The struct sent from the server containing console messages
+ * Return struct after finishing a Git Clone action
  *
- * @param type The type of message. Currently unknown what varients exist
- * @param line The actual content of the console messages
+ * @param folder_name The name of the folder the repo was cloned into
+ * @param commit The HEAD commit hash after the clone
+ * @param branch The branch that was cloned
  *
  * @internal
  */
-export interface ConsoleMessage {
-    type: string;
-    line: string;
+export interface GitCloneResult {
+    folder_name: string;
+    commit: string;
+    branch: string;
 }
 /**
- * Struct used to initiate a Git Clone action
+ * Struct returned after a Git Pull action finishes.
  *
- * @param dir The directory to clone into
- * @param url The HTTPS URL to clone
- * @param branch The repository branch
- * @param authkey The authentication key to use when pulling
+ * @param commit The HEAD commit hash after the pull
+ * @param branch The branch that was pulled
+ * @param files_changed How many files changed (0 when already up to date)
+ * @param up_to_date Whether the repo was already up to date
  *
  * @internal
  */
-export interface GitCloneData {
-    dir: string;
-    url: string;
+export interface GitPullResult {
+    commit: string;
     branch: string;
-    authkey?: string | undefined;
+    files_changed: number;
+    up_to_date: boolean;
 }
 /**
- * Return struct after finishing a Git Clone action
+ * Payload for an `fs:request`. Sent as a JSON string; `op`-specific fields go
+ * alongside `req` and `op`.
  *
- * @param isPrivate Whether or not the repository is private
+ * @internal
+ */
+export interface FsRequest {
+    req: string;
+    op: string;
+    directory?: string;
+    [key: string]: any;
+}
+/**
+ * The `fs:result` success envelope; `data` carries the op-specific payload.
  *
  * @internal
  */
-export interface GitCloneResult {
-    isPrivate: boolean;
+export interface FsResult<T = any> {
+    req: string;
+    data?: T;
 }
 /**
- * Struct used to initiate a Git Pull action
+ * The `fs:error` envelope. Errors arrive as a separate event from `fs:result`,
+ * correlated by `req` (e.g. `code: "auth_required"` / `"auth_invalid"`).
  *
- * @param dir The directory to pull
- * @param authkey The authentication key to use when pulling
+ * @internal
+ */
+export interface FsError {
+    req: string;
+    code: string;
+    message: string;
+}
+/**
+ * The parsed `fs:progress` envelope, correlated by `req`. Comes in two shapes:
+ * text lines (`kind: "stdout" | "stderr"`, `line`) and structured progress
+ * (`kind: "progress"` with `phase`/`current`/`total`/`percent`).
  *
  * @internal
  */
-export interface GitPullData {
-    dir: string;
-    authkey?: string;
+export interface FsProgress {
+    req: string;
+    kind: "stdout" | "stderr" | "progress" | string;
+    line?: string;
+    phase?: string;
+    current?: number;
+    total?: number;
+    percent?: number;
 }
 /**
- * Struct returned after a Git Pull action finishes
+ * Result of a `git-status` op. Repo-specific fields are absent when
+ * `is_repo` is false.
  *
- * @param output The actual output
- * @param isPrivate Whether or not the repository is private
+ * @internal
+ */
+export interface GitStatusResult {
+    is_repo: boolean;
+    ahead: number;
+    behind: number;
+    dirty: boolean;
+    repo_root?: string;
+    branch?: string;
+    commit?: string;
+    remote_url?: string;
+}
+/**
+ * A single entry in a `list` op result.
  *
  * @internal
  */
-export interface GitPullResult {
-    output: string;
-    isPrivate: boolean;
+export interface FileEntry {
+    name: string;
+    created: string;
+    modified: string;
+    mode: string;
+    mode_bits: string;
+    size: number;
+    directory: boolean;
+    file: boolean;
+    symlink: boolean;
+    mime: string;
+    child_count?: number;
+}
+/**
+ * Options for a `list` op.
+ *
+ * @internal
+ */
+export interface ListOptions {
+    search?: string;
+    page?: number;
+    perPage?: number;
+    sort?: string;
+    sortDir?: "asc" | "desc";
+}
+/**
+ * Result of a `list` op: a paginated directory listing.
+ *
+ * @internal
+ */
+export interface ListResult {
+    data: FileEntry[];
+    meta: {
+        pagination: {
+            count: number;
+            currentPage: number;
+            perPage: number;
+            total: number;
+            totalPages: number;
+        };
+    };
 }
 /**
  * An individual filesearch result
@@ -123,10 +212,33 @@ export interface FilesearchResults {
     tooMany: boolean;
 }
 /**
- * The events that can be sent from the server to the client
+ * Result of an op that just reports success (e.g. `mkdir`).
+ *
+ * @internal
+ */
+export interface FsOkResult {
+    ok: boolean;
+}
+/**
+ * Result of a `conflicts` op — the subset of the given paths that already
+ * exist / would conflict.
+ *
+ * @internal
+ */
+export interface ConflictsResult {
+    conflicts: string[];
+}
+/**
+ * The websocket type used throughout the pool.
+ *
+ * The backend no longer speaks Socket.IO, so this is our {@link WispWebSocket}
+ * adapter rather than a Socket.IO `Socket`. The {@link ServerToClientEvents}
+ * and {@link ClientToServerEvents} interfaces above document the event names
+ * but are no longer enforced by the adapter's looser `(...args: any[])` API.
+ *
  * @internal
  */
-export type WispWebsocket = Socket<ServerToClientEvents, ClientToServerEvents>;
+export type WispWebsocket = WispWebSocket;
 /**
  * A single worker in the Websocket Pool
  *
@@ -137,7 +249,9 @@ interface PoolWorker {
     socket: WispWebsocket;
     idx: number;
     token: string;
-    ready: boolean;
+    url: string;
+    connected: boolean;
+    busy: boolean;
     done: boolean;
     logger: Logger;
 }
@@ -149,11 +263,36 @@ interface PoolWorker {
  * @internal
  */
 declare class PoolWorker {
+    private intentionalDisconnect;
+    private reconnectAttempts;
+    private readonly maxReconnectAttempts;
     constructor(pool: WebsocketPool);
+    private createSocket;
+    private start;
     connect(): Promise<void>;
+    private handleDisconnect;
     disconnect(): Promise<void>;
     private processWork;
 }
+/**
+ * A queued unit of work plus a hook to reject it if it can never run (e.g. the
+ * pool has no live workers, or it waited too long to be picked up).
+ *
+ * @internal
+ */
+interface QueueItem {
+    task: (worker: PoolWorker) => Promise<void>;
+    reject: (reason?: any) => void;
+}
+/**
+ * Fetches fresh websocket details (url + token) for reconnects.
+ *
+ * @internal
+ */
+export type DetailsProvider = () => Promise<{
+    url: string;
+    token: string;
+}>;
 /**
  * Struct used to manage a pool of WebSocket workers
  */
@@ -161,9 +300,12 @@ export interface WebsocketPool {
     workers: PoolWorker[];
     token: string;
     url: string;
+    origin: string;
     maxWorkers: number;
+    acquireTimeout: number;
+    refreshDetails?: DetailsProvider;
     logger: Logger;
-    queue: ((worker: PoolWorker) => Promise<any>)[];
+    queue: QueueItem[];
 }
 /**
  * A pool of {@link PoolWorker}s
@@ -177,8 +319,10 @@ export interface WebsocketPool {
  * @internal
  */
 export declare class WebsocketPool {
-    constructor(url: string, token: string);
+    constructor(url: string, token: string, origin: string, refreshDetails?: DetailsProvider);
     getWork(): ((worker: PoolWorker) => Promise<any>) | undefined;
+    private allWorkersDone;
+    onWorkerDone(): void;
     disconnect(): Promise<void>;
     run(work: (worker: PoolWorker) => Promise<any>): Promise<any>;
 }