@relayfile/client 0.10.52 → 0.10.54

package/dist/client.d.ts

@@ -69,6 +69,19 @@ export interface RelayfileClientOptions {
     startTimeoutMs?: number;
     /** Per-request timeout. A hung socket rejects instead of blocking forever. */
     requestTimeoutMs?: number;
+    /**
+     * Maximum time allowed to discover a stale daemon through `lsof`.
+     * Clamped to 5–10 seconds so loaded hosts get enough time without an
+     * unbounded control-plane replacement wait.
+     */
+    staleDaemonDiscoveryTimeoutMs?: number;
+    /**
+     * Maximum time allowed for a stale daemon to release the socket and exit
+     * after SIGTERM. Clamped to 5–10 seconds and never inherited from
+     * `startTimeoutMs`, so an oversized or non-finite start budget cannot make
+     * stale-daemon replacement wait forever.
+     */
+    staleDaemonTerminationTimeoutMs?: number;
 }
 export declare class RelayfileControlPlaneClient {
     private readonly socketPath;
@@ -76,6 +89,8 @@ export declare class RelayfileControlPlaneClient {
     private readonly autoStart;
     private readonly startTimeoutMs;
     private readonly requestTimeoutMs;
+    private readonly staleDaemonDiscoveryTimeoutMs;
+    private readonly staleDaemonTerminationTimeoutMs;
     private ready;
     constructor(options?: RelayfileClientOptions);
     private createHTTPRequest;
@@ -87,6 +102,7 @@ export declare class RelayfileControlPlaneClient {
     private spawnDaemon;
     private startDaemonAndConnect;
     private stopStaleDaemon;
+    private isProcessAlive;
     private socketOwnerPids;
     /** Resolve a Unix-socket owner without external tools on standard Linux hosts. */
     private linuxSocketOwnerPids;

package/dist/client.js

@@ -23,6 +23,10 @@ export const RELAYFILE_API_VERSION = 3;
 export const MIN_RELAYFILE_VERSION = '0.10.17';
 /** First published relayfile binary that can replace a stale daemon for API v3. */
 const MIN_RELAYFILE_VERSION_FOR_CURRENT_API = '0.10.21';
+const DEFAULT_STALE_DAEMON_DISCOVERY_TIMEOUT_MS = 5000;
+const MAX_STALE_DAEMON_DISCOVERY_TIMEOUT_MS = 10000;
+const DEFAULT_STALE_DAEMON_TERMINATION_TIMEOUT_MS = 5000;
+const MAX_STALE_DAEMON_TERMINATION_TIMEOUT_MS = 10000;
 const SEMVER_RE = /^\d+\.\d+\.\d+(?:[-+].*)?$/;
 /** First semver-looking token in a string (tolerates a leading `v` and surrounding words). */
 export function firstSemver(value) {
@@ -106,6 +110,8 @@ export class RelayfileControlPlaneClient {
     autoStart;
     startTimeoutMs;
     requestTimeoutMs;
+    staleDaemonDiscoveryTimeoutMs;
+    staleDaemonTerminationTimeoutMs;
     ready;
     constructor(options = {}) {
         this.socketPath = options.socketPath ?? defaultRelayfileSocketPath();
@@ -113,6 +119,14 @@ export class RelayfileControlPlaneClient {
         this.autoStart = options.autoStart ?? process.env.RELAYFILE_REQUIRE_DAEMON !== '1';
         this.startTimeoutMs = options.startTimeoutMs ?? 5000;
         this.requestTimeoutMs = options.requestTimeoutMs ?? 10000;
+        const requestedStaleDaemonDiscoveryTimeoutMs = options.staleDaemonDiscoveryTimeoutMs;
+        this.staleDaemonDiscoveryTimeoutMs = Number.isFinite(requestedStaleDaemonDiscoveryTimeoutMs)
+            ? Math.min(MAX_STALE_DAEMON_DISCOVERY_TIMEOUT_MS, Math.max(DEFAULT_STALE_DAEMON_DISCOVERY_TIMEOUT_MS, requestedStaleDaemonDiscoveryTimeoutMs))
+            : DEFAULT_STALE_DAEMON_DISCOVERY_TIMEOUT_MS;
+        const requestedStaleDaemonTerminationTimeoutMs = options.staleDaemonTerminationTimeoutMs;
+        this.staleDaemonTerminationTimeoutMs = Number.isFinite(requestedStaleDaemonTerminationTimeoutMs)
+            ? Math.min(MAX_STALE_DAEMON_TERMINATION_TIMEOUT_MS, Math.max(DEFAULT_STALE_DAEMON_TERMINATION_TIMEOUT_MS, requestedStaleDaemonTerminationTimeoutMs))
+            : DEFAULT_STALE_DAEMON_TERMINATION_TIMEOUT_MS;
     }
     createHTTPRequest(options, onResponse) {
         return request(options, onResponse);
@@ -245,8 +259,15 @@ export class RelayfileControlPlaneClient {
                 hello = await this.startDaemonAndConnect(installedVersion);
             }
             catch (err) {
-                if (err instanceof RelayfileControlPlaneError && err.code === 'VERSION_INCOMPATIBLE') {
-                    throw err;
+                if (err instanceof RelayfileControlPlaneError) {
+                    // VERSION_INCOMPATIBLE from the replacement handshake and the typed
+                    // stale-daemon discovery/termination codes are actionable as-is;
+                    // wrapping them would hide the diagnosis ensureReady callers need.
+                    if (err.code === 'VERSION_INCOMPATIBLE' ||
+                        err.code === 'STALE_DAEMON_DISCOVERY_FAILED' ||
+                        err.code === 'STALE_DAEMON_STOP_FAILED') {
+                        throw err;
+                    }
                 }
                 throw this.versionMismatchError(hello, installedVersion, `Automatic stale-daemon replacement failed: ${err instanceof Error ? err.message : String(err)}`);
             }
@@ -321,14 +342,25 @@ export class RelayfileControlPlaneClient {
             process.kill(pids[0], 'SIGTERM');
         }
         catch (err) {
-            throw new Error(`could not stop stale relayfile control-plane pid ${pids[0]}: ${err instanceof Error ? err.message : String(err)}`);
+            throw new RelayfileControlPlaneError('STALE_DAEMON_STOP_FAILED', `could not stop stale relayfile control-plane pid ${pids[0]}: ${err instanceof Error ? err.message : String(err)}`);
         }
-        const deadline = Date.now() + this.startTimeoutMs;
-        while (existsSync(this.socketPath) && Date.now() < deadline) {
+        const deadline = Date.now() + this.staleDaemonTerminationTimeoutMs;
+        while ((existsSync(this.socketPath) || this.isProcessAlive(pids[0])) &&
+            Date.now() < deadline) {
             await sleep(50);
         }
-        if (existsSync(this.socketPath)) {
-            throw new Error(`stale relayfile control-plane pid ${pids[0]} did not release ${this.socketPath} within ${this.startTimeoutMs}ms`);
+        if (existsSync(this.socketPath) || this.isProcessAlive(pids[0])) {
+            throw new RelayfileControlPlaneError('STALE_DAEMON_STOP_FAILED', `stale relayfile control-plane pid ${pids[0]} did not release ${this.socketPath} ` +
+                `and exit within ${this.staleDaemonTerminationTimeoutMs}ms`);
+        }
+    }
+    isProcessAlive(pid) {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (err) {
+            return err.code !== 'ESRCH';
         }
     }
     async socketOwnerPids() {
@@ -340,14 +372,22 @@ export class RelayfileControlPlaneClient {
         if (process.platform === 'win32') {
             throw new Error('automatic stale-daemon replacement is not supported on Windows; stop the running relayfile control-plane manually');
         }
-        const result = await this.runCommand('lsof', ['-t', '--', this.socketPath], 1000);
+        const result = await this.runCommand('lsof', ['-t', '--', this.socketPath], this.staleDaemonDiscoveryTimeoutMs);
         if (!result) {
-            throw new Error(`could not run \`lsof\` to identify the process serving ${this.socketPath} ` +
-                `(it is not installed, not on PATH, or did not exit within 1000ms); ` +
+            throw new RelayfileControlPlaneError('STALE_DAEMON_DISCOVERY_FAILED', `could not run \`lsof\` to identify the process serving ${this.socketPath} ` +
+                `(it is not installed or not on PATH); ` +
                 `install lsof or stop the stale relayfile control-plane manually`);
         }
+        if (result.timedOut) {
+            throw new RelayfileControlPlaneError('STALE_DAEMON_DISCOVERY_FAILED', `\`lsof\` timed out after ${this.staleDaemonDiscoveryTimeoutMs}ms while identifying ` +
+                `the process serving ${this.socketPath}${result.stderr.trim() ? ` (stderr: ${result.stderr.trim()})` : ''}`);
+        }
+        if (result.commandError) {
+            throw new RelayfileControlPlaneError('STALE_DAEMON_DISCOVERY_FAILED', `could not run \`lsof\` to identify the process serving ${this.socketPath}: ` +
+                `${result.commandError}${result.stderr.trim() ? ` (stderr: ${result.stderr.trim()})` : ''}`);
+        }
         if (result.code !== 0) {
-            throw new Error(`lsof could not identify the process serving ${this.socketPath} (exit ${result.code}${result.stderr.trim() ? `: ${result.stderr.trim()}` : ''})`);
+            throw new RelayfileControlPlaneError('STALE_DAEMON_DISCOVERY_FAILED', `lsof could not identify the process serving ${this.socketPath} (exit ${result.code}${result.stderr.trim() ? `: ${result.stderr.trim()}` : ''})`);
         }
         return [
             ...new Set(result.stdout
@@ -466,11 +506,11 @@ export class RelayfileControlPlaneClient {
             child.stderr?.on('data', (chunk) => {
                 stderr += String(chunk);
             });
-            child.once('error', () => finish());
+            child.once('error', (err) => finish({ stdout, stderr, code: null, commandError: err instanceof Error ? err.message : String(err) }));
             child.once('close', (code) => finish({ stdout, stderr, code }));
             timeout = setTimeout(() => {
                 child.kill();
-                finish();
+                finish({ stdout, stderr, code: null, timedOut: true });
             }, timeoutMs);
             timeout.unref?.();
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/client",
-  "version": "0.10.52",
+  "version": "0.10.54",
   "description": "Typed client for the relayfile local control-plane (unix-socket HTTP/JSON), generated from the authoritative OpenAPI contract",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",