@vex-chat/libvex 5.0.0 → 5.2.0

package/src/Client.ts

@@ -160,6 +160,12 @@ export interface ClientOptions {
     saveHistory?: boolean;
     /** Use `http/ws` instead of `https/wss`. Intended for local/dev environments. */
     unsafeHttp?: boolean;
+    /**
+     * When set (non-empty), sent as `x-dev-api-key` on every HTTP request.
+     * Spire omits in-process rate limits when this matches the server's `DEV_API_KEY`
+     * (local / load-testing only — never use in production).
+     */
+    devApiKey?: string;
 }
 
 /**
@@ -850,6 +856,16 @@ export class Client {
     private readonly forwarded = new Set<string>();
 
     private readonly host: string;
+    /**
+     * Node-only: per-client HTTP(S) agents (see `init()` + `storage/node/http-agents`).
+     * Dropped on `close()` so idle keep-alive sockets do not keep the process alive.
+     */
+    private nodeHttpAgents?: {
+        http: { destroy(): void };
+        https: { destroy(): void };
+    };
+    /** Cancels in-flight axios work on `close()` so `postAuth`/`getMail` cannot hang forever. */
+    private readonly httpAbortController = new AbortController();
     private readonly http: AxiosInstance;
     private readonly idKeys: KeyPair | null;
     private isAlive: boolean = true;
@@ -932,7 +948,14 @@ export class Client {
             void this.close(true);
         });
 
-        this.http = axios.create({ responseType: "arraybuffer" });
+        this.http = axios.create({
+            responseType: "arraybuffer",
+            signal: this.httpAbortController.signal,
+        });
+        const devKey = options?.devApiKey?.trim();
+        if (devKey !== undefined && devKey.length > 0) {
+            this.http.defaults.headers.common["x-dev-api-key"] = devKey;
+        }
 
         this.socket = new WebSocketAdapter(this.prefixes.WS + this.host);
         this.socket.onerror = () => {};
@@ -1023,6 +1046,32 @@ export class Client {
         return xMnemonic(xKDF(XUtils.decodeHex(session.fingerprint)));
     }
 
+    /**
+     * True when running under Node (has `process.versions`).
+     * Uses indirect lookup so the bare `process` global never appears in
+     * source that the platform-guard plugin scans.
+     */
+    private static isNodeRuntime(): boolean {
+        try {
+            const g = Object.getOwnPropertyDescriptor(
+                globalThis,
+                "\u0070rocess",
+            );
+            if (!g) return false;
+            const proc: unknown =
+                typeof g.get === "function" ? g.get() : g.value;
+            if (typeof proc !== "object" || proc === null) {
+                return false;
+            }
+            return (
+                "versions" in proc &&
+                typeof (proc as { versions?: unknown }).versions === "object"
+            );
+        } catch {
+            return false;
+        }
+    }
+
     /**
      * Browser-safe NODE_ENV accessor.
      * Uses indirect lookup so the bare `process` global never appears in
@@ -1062,6 +1111,15 @@ export class Client {
         }
     }
 
+    /**
+     * Fresh read of the `manuallyClosing` flag for async loops — direct property checks
+     * after `await` are flagged as always-false by control-flow analysis even though
+     * `close()` can run concurrently.
+     */
+    private isManualCloseInFlight(): boolean {
+        return this.manuallyClosing;
+    }
+
     /**
      * Closes the client — disconnects the WebSocket, shuts down storage,
      * and emits `closed` unless `muteEvent` is `true`.
@@ -1070,9 +1128,16 @@ export class Client {
      */
     public async close(muteEvent = false): Promise<void> {
         this.manuallyClosing = true;
+        this.httpAbortController.abort();
         this.socket.close();
         await this.database.close();
 
+        if (this.nodeHttpAgents) {
+            this.nodeHttpAgents.http.destroy();
+            this.nodeHttpAgents.https.destroy();
+            delete this.nodeHttpAgents;
+        }
+
         if (this.pingInterval) {
             clearInterval(this.pingInterval);
         }
@@ -1539,6 +1604,9 @@ export class Client {
         }
 
         if (!this.xKeyRing) {
+            if (this.manuallyClosing) {
+                return;
+            }
             throw new Error("Key ring not initialized.");
         }
 
@@ -1765,6 +1833,10 @@ export class Client {
     }
 
     private async forward(message: Message) {
+        if (this.isManualCloseInFlight()) {
+            return;
+        }
+
         const copy = { ...message };
 
         if (this.forwarded.has(copy.mailID)) {
@@ -1779,11 +1851,10 @@ export class Client {
 
         const msgBytes = Uint8Array.from(msgpack.encode(copy));
 
-        const devices = await this.getUserDeviceList(this.getUser().userID);
-
-        if (!devices) {
-            throw new Error("Couldn't get own devices.");
-        }
+        const devices = await this.fetchUserDeviceListWithBackoff(
+            this.getUser().userID,
+            "own",
+        );
         const promises = [];
         for (const device of devices) {
             if (device.deviceID !== this.getDevice().deviceID) {
@@ -1881,6 +1952,9 @@ export class Client {
     }
 
     private async getMail(): Promise<void> {
+        if (this.manuallyClosing) {
+            return;
+        }
         while (this.fetchingMail) {
             await sleep(500);
         }
@@ -2034,22 +2108,85 @@ export class Client {
         return this.user;
     }
 
+    private deviceListFailureDetail(err: unknown): string {
+        if (!isAxiosError(err)) {
+            return "";
+        }
+        const st = err.response?.status;
+        if (typeof st === "number") {
+            return ` (HTTP ${String(st)})`;
+        }
+        if (err.code !== undefined) {
+            return ` (${err.code})`;
+        }
+        return "";
+    }
+
+    /**
+     * Single GET for `/user/:id/devices`. On failure returns `null` (swallows errors)
+     * — callers that need reliability should use `fetchUserDeviceListWithBackoff`.
+     * Similar “best effort null” patterns elsewhere: `getChannelByID`,
+     * `getDeviceByID` (HTTP leg), `getToken`, emoji upload fallbacks.
+     */
     private async getUserDeviceList(userID: string): Promise<Device[] | null> {
         try {
-            const res = await this.http.get(
-                this.getHost() + "/user/" + userID + "/devices",
-            );
-            const devices = decodeAxios(DeviceArrayCodec, res.data);
-            for (const device of devices) {
-                this.deviceRecords[device.deviceID] = device;
-            }
-
-            return devices;
+            return await this.fetchUserDeviceListOnce(userID);
         } catch (_err: unknown) {
             return null;
         }
     }
 
+    private async fetchUserDeviceListOnce(userID: string): Promise<Device[]> {
+        if (this.isManualCloseInFlight()) {
+            return [];
+        }
+        const res = await this.http.get(
+            this.getHost() + "/user/" + userID + "/devices",
+        );
+        const devices = decodeAxios(DeviceArrayCodec, res.data);
+        for (const device of devices) {
+            this.deviceRecords[device.deviceID] = device;
+        }
+        return devices;
+    }
+
+    /**
+     * DM / forward paths need the peer’s (or self) device rows under load: bounded
+     * retries with exponential backoff (same shape as session pubkey hydration).
+     */
+    private async fetchUserDeviceListWithBackoff(
+        userID: string,
+        label: "peer" | "own",
+    ): Promise<Device[]> {
+        const base =
+            label === "own"
+                ? "Couldn't get own devices"
+                : "Couldn't get device list";
+        let lastErr: unknown;
+        for (let attempt = 0; attempt < 5; attempt++) {
+            if (this.isManualCloseInFlight()) {
+                return [];
+            }
+            if (attempt > 0) {
+                const delayMs = 100 * 2 ** (attempt - 1);
+                // Chunk the delay so close() can finish before we retry HTTP.
+                const chunkMs = 10;
+                for (let elapsed = 0; elapsed < delayMs; elapsed += chunkMs) {
+                    if (this.isManualCloseInFlight()) {
+                        return [];
+                    }
+                    await sleep(Math.min(chunkMs, delayMs - elapsed));
+                }
+            }
+            try {
+                return await this.fetchUserDeviceListOnce(userID);
+            } catch (err: unknown) {
+                lastErr = err;
+            }
+        }
+        throw new Error(`${base}${this.deviceListFailureDetail(lastErr)}`);
+    }
+
     private async getUserList(channelID: string): Promise<User[]> {
         const res = await this.http.post(
             this.getHost() + "/userList/" + channelID,
@@ -2077,6 +2214,28 @@ export class Client {
         }
     }
 
+    /**
+     * Pipeline for decrypted messages — registered in `init`. After `close()` sets
+     * `manuallyClosing`, this becomes a no-op so fire-and-forget `forward` does not
+     * race HTTP teardown (we avoid `off()` here — it can interact badly with emit).
+     */
+    private readonly onInternalMessage = (message: Message): void => {
+        if (this.isManualCloseInFlight()) {
+            return;
+        }
+        if (message.direction === "outgoing" && !message.forward) {
+            void this.forward(message);
+        }
+
+        if (
+            message.direction === "incoming" &&
+            message.recipient === message.sender
+        ) {
+            return;
+        }
+        void this.database.saveMessage(message);
+    };
+
     /**
      * Initializes the keyring. This must be called before anything else.
      */
@@ -2086,20 +2245,16 @@ export class Client {
         }
         this.hasInit = true;
 
-        await this.populateKeyRing();
-        this.emitter.on("message", (message) => {
-            if (message.direction === "outgoing" && !message.forward) {
-                void this.forward(message);
-            }
+        if (Client.isNodeRuntime()) {
+            const { attachNodeAgentsToAxios, createNodeHttpAgents } =
+                await import("./storage/node/http-agents.js");
+            const agents = createNodeHttpAgents();
+            this.nodeHttpAgents = agents;
+            attachNodeAgentsToAxios(this.http, agents);
+        }
 
-            if (
-                message.direction === "incoming" &&
-                message.recipient === message.sender
-            ) {
-                return;
-            }
-            void this.database.saveMessage(message);
-        });
+        await this.populateKeyRing();
+        this.emitter.on("message", this.onInternalMessage);
         this.emitter.emit("ready");
     }
 
@@ -2218,6 +2373,9 @@ export class Client {
 
     private newEphemeralKeys() {
         if (!this.xKeyRing) {
+            if (this.manuallyClosing) {
+                return;
+            }
             throw new Error("Key ring not initialized.");
         }
         this.xKeyRing.ephemeralKeys = xBoxKeyPair();
@@ -2275,6 +2433,9 @@ export class Client {
     private async postAuth() {
         let count = 0;
         for (;;) {
+            if (this.isManualCloseInFlight()) {
+                return;
+            }
             try {
                 await this.getMail();
                 count++;
@@ -2285,7 +2446,17 @@ export class Client {
                     count = 0;
                 }
             } catch {}
-            await sleep(1000 * 60);
+            if (this.isManualCloseInFlight()) {
+                return;
+            }
+            // Chunk the idle delay so `close()` can unwind instead of waiting
+            // out one full 60s timer (which would keep the process alive).
+            for (let i = 0; i < 60; i++) {
+                if (this.isManualCloseInFlight()) {
+                    return;
+                }
+                await sleep(1000);
+            }
         }
     }
 
@@ -2303,6 +2474,10 @@ export class Client {
         }
         this.seenMailIDs.add(mail.mailID);
 
+        if (this.manuallyClosing) {
+            return;
+        }
+
         this.sendReceipt(new Uint8Array(mail.nonce));
         let timeout = 1;
         while (this.reading) {
@@ -2313,6 +2488,9 @@ export class Client {
 
         try {
             const healSession = async () => {
+                if (this.manuallyClosing || !this.xKeyRing) {
+                    return;
+                }
                 const deviceEntry = await this.getDeviceByID(mail.sender);
                 const [user, _err] = await this.fetchUser(mail.authorID);
                 if (deviceEntry && user) {
@@ -2362,7 +2540,7 @@ export class Client {
                     const EK_A = ephKey;
 
                     if (!this.xKeyRing) {
-                        throw new Error("Key ring not initialized.");
+                        return;
                     }
                     // my private keys
                     const IK_B = this.xKeyRing.identityKeys.secretKey;
@@ -2920,17 +3098,10 @@ export class Client {
                 throw new Error("Couldn't get user entry.");
             }
 
-            let deviceList = await this.getUserDeviceList(userID);
-            if (!deviceList) {
-                let retries = 0;
-                while (!deviceList) {
-                    deviceList = await this.getUserDeviceList(userID);
-                    retries++;
-                    if (retries > 3) {
-                        throw new Error("Couldn't get device list.");
-                    }
-                }
-            }
+            const deviceList = await this.fetchUserDeviceListWithBackoff(
+                userID,
+                "peer",
+            );
             const mailID = uuid.v4();
             const promises: Array<Promise<void>> = [];
             for (const device of deviceList) {

package/src/storage/node/http-agents.ts

@@ -0,0 +1,33 @@
+import type { AxiosInstance } from "axios";
+
+/**
+ * Node-only HTTP(S) agents for libvex axios — lives under `storage/node/` so the
+ * platform-guard plugin allows `node:http` / `node:https` (see poison-node-imports).
+ */
+import * as nodeHttp from "node:http";
+import * as nodeHttps from "node:https";
+
+export interface NodeHttpAgentPair {
+    readonly http: nodeHttp.Agent;
+    readonly https: nodeHttps.Agent;
+}
+
+export function createNodeHttpAgents(): NodeHttpAgentPair {
+    return {
+        http: new nodeHttp.Agent({ keepAlive: true }),
+        https: new nodeHttps.Agent({ keepAlive: true }),
+    };
+}
+
+export function attachNodeAgentsToAxios(
+    instance: AxiosInstance,
+    agents: NodeHttpAgentPair,
+): void {
+    instance.defaults.httpAgent = agents.http;
+    instance.defaults.httpsAgent = agents.https;
+}
+
+export function destroyNodeHttpAgents(agents: NodeHttpAgentPair): void {
+    agents.http.destroy();
+    agents.https.destroy();
+}