wispjs 2.4.0 → 3.0.1

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>;
 }

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;
+}