@vex-chat/libvex 4.0.0 → 5.1.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,14 @@ 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 };
+    };
     private readonly http: AxiosInstance;
     private readonly idKeys: KeyPair | null;
     private isAlive: boolean = true;
@@ -933,6 +947,10 @@ export class Client {
         });
 
         this.http = axios.create({ responseType: "arraybuffer" });
+        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 +1041,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
@@ -1034,26 +1078,43 @@ export class Client {
                 globalThis,
                 "\u0070rocess",
             );
-            if (!g || typeof g.value !== "object" || g.value === null) {
+            if (!g) return undefined;
+            // Node 24+ exposes `process` as an accessor (get/set), not a value.
+            const proc: unknown =
+                typeof g.get === "function" ? g.get() : g.value;
+            if (typeof proc !== "object" || proc === null) {
                 return undefined;
             }
-            const env: unknown = Object.getOwnPropertyDescriptor(
-                g.value,
-                "env",
-            )?.value;
+            const envDesc = Object.getOwnPropertyDescriptor(proc, "env");
+            if (!envDesc) return undefined;
+            const env: unknown =
+                typeof envDesc.get === "function"
+                    ? envDesc.get()
+                    : envDesc.value;
             if (typeof env !== "object" || env === null) {
                 return undefined;
             }
-            const val: unknown = Object.getOwnPropertyDescriptor(
-                env,
-                "NODE_ENV",
-            )?.value;
+            const valDesc = Object.getOwnPropertyDescriptor(env, "NODE_ENV");
+            if (!valDesc) return undefined;
+            const val: unknown =
+                typeof valDesc.get === "function"
+                    ? valDesc.get()
+                    : valDesc.value;
             return typeof val === "string" ? val : undefined;
         } catch {
             return undefined;
         }
     }
 
+    /**
+     * 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`.
@@ -1065,6 +1126,12 @@ export class Client {
         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);
         }
@@ -1085,9 +1152,12 @@ export class Client {
      * You can check whoami() to see before calling connect().
      */
     public async connect(): Promise<void> {
-        const { token, user } = await this.whoami();
-        this.token = token;
-        this.http.defaults.headers.common.Authorization = `Bearer ${token}`;
+        if (!this.token) {
+            throw new Error(
+                "No token — call login() or loginWithDeviceKey() first.",
+            );
+        }
+        const { user } = await this.whoami();
         this.setUser(user);
 
         this.device = await this.retrieveOrCreateDevice();
@@ -1385,7 +1455,6 @@ export class Client {
      */
     public async whoami(): Promise<{
         exp: number;
-        token: string;
         user: User;
     }> {
         const res = await this.http.post(this.getHost() + "/whoami");
@@ -1529,6 +1598,9 @@ export class Client {
         }
 
         if (!this.xKeyRing) {
+            if (this.manuallyClosing) {
+                return;
+            }
             throw new Error("Key ring not initialized.");
         }
 
@@ -1769,11 +1841,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) {
@@ -1871,6 +1942,9 @@ export class Client {
     }
 
     private async getMail(): Promise<void> {
+        if (this.manuallyClosing) {
+            return;
+        }
         while (this.fetchingMail) {
             await sleep(500);
         }
@@ -2024,22 +2098,86 @@ 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[]> {
+        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 (attempt > 0) {
+                if (this.isManualCloseInFlight()) {
+                    throw new Error(
+                        `${base}${this.deviceListFailureDetail(lastErr)}`,
+                    );
+                }
+                const delayMs = 100 * 2 ** (attempt - 1);
+                // Chunk the delay to allow close() to interrupt
+                const chunkMs = 10;
+                for (let elapsed = 0; elapsed < delayMs; elapsed += chunkMs) {
+                    if (this.isManualCloseInFlight()) {
+                        throw new Error(
+                            `${base}${this.deviceListFailureDetail(lastErr)}`,
+                        );
+                    }
+                    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,
@@ -2076,6 +2214,14 @@ export class Client {
         }
         this.hasInit = true;
 
+        if (Client.isNodeRuntime()) {
+            const { attachNodeAgentsToAxios, createNodeHttpAgents } =
+                await import("./storage/node/http-agents.js");
+            const agents = createNodeHttpAgents();
+            this.nodeHttpAgents = agents;
+            attachNodeAgentsToAxios(this.http, agents);
+        }
+
         await this.populateKeyRing();
         this.emitter.on("message", (message) => {
             if (message.direction === "outgoing" && !message.forward) {
@@ -2208,6 +2354,9 @@ export class Client {
 
     private newEphemeralKeys() {
         if (!this.xKeyRing) {
+            if (this.manuallyClosing) {
+                return;
+            }
             throw new Error("Key ring not initialized.");
         }
         this.xKeyRing.ephemeralKeys = xBoxKeyPair();
@@ -2265,6 +2414,9 @@ export class Client {
     private async postAuth() {
         let count = 0;
         for (;;) {
+            if (this.isManualCloseInFlight()) {
+                return;
+            }
             try {
                 await this.getMail();
                 count++;
@@ -2275,7 +2427,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);
+            }
         }
     }
 
@@ -2293,6 +2455,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) {
@@ -2303,6 +2469,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) {
@@ -2352,7 +2521,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;
@@ -2910,17 +3079,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/__tests__/harness/shared-suite.ts

@@ -23,6 +23,7 @@ export function platformSuite(
 
         beforeAll(async () => {
             const SK = Client.generateSecretKey();
+
             const opts: ClientOptions = {
                 inMemoryDb: true,
                 ...apiUrlOverrideFromEnv(),

package/src/codecs.ts

@@ -70,7 +70,6 @@ export const DeviceChallengeCodec = createCodec(
 export const WhoamiCodec = createCodec(
     z.object({
         exp: z.number(),
-        token: z.string(),
         user: UserSchema,
     }),
 );

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