@relayfile/client 0.10.26 → 0.10.27

package/dist/client.d.ts

@@ -13,9 +13,8 @@ import type { components } from './generated/control-plane.js';
 /** Control-plane API version this client speaks. Bump when adding required endpoint support. */
 export declare const RELAYFILE_API_VERSION = 3;
 /**
- * Minimum `relayfile` daemon version this client requires. The control-plane
- * first shipped in 0.10.17, so anything that answers `/v1/hello` is already >=
- * this — API compatibility is enforced by RELAYFILE_API_VERSION.
+ * Minimum `relayfile` daemon version this client requires. API compatibility is
+ * enforced independently through supportedApiVersions.
  */
 export declare const MIN_RELAYFILE_VERSION = "0.10.17";
 /** First semver-looking token in a string (tolerates a leading `v` and surrounding words). */
@@ -34,7 +33,11 @@ export declare function defaultRelayfileSocketPath(): string;
 export declare class RelayfileControlPlaneError extends Error {
     readonly code: string;
     readonly status?: number | undefined;
-    constructor(code: string, message: string, status?: number | undefined);
+    /** True only for connection failures that may clear while a daemon starts. */
+    readonly transient: boolean;
+    constructor(code: string, message: string, status?: number | undefined, 
+    /** True only for connection failures that may clear while a daemon starts. */
+    transient?: boolean);
 }
 type Schemas = components['schemas'];
 export type HelloResponse = Schemas['HelloResponse'];
@@ -75,12 +78,23 @@ export declare class RelayfileControlPlaneClient {
     private readonly requestTimeoutMs;
     private ready;
     constructor(options?: RelayfileClientOptions);
+    private createHTTPRequest;
     /** Low-level request over the unix socket. Throws RelayfileControlPlaneError. */
     private rawRequest;
     /** Connect (auto-starting the daemon if configured), version-negotiating once. */
     ensureReady(): Promise<void>;
     private connectAndNegotiate;
+    private spawnDaemon;
     private startDaemonAndConnect;
+    private stopStaleDaemon;
+    private socketOwnerPids;
+    /** Resolve a Unix-socket owner without external tools on standard Linux hosts. */
+    private linuxSocketOwnerPids;
+    private versionMismatchError;
+    private versionRejectionError;
+    private restartCommand;
+    private installedBinaryVersion;
+    private runCommand;
     hello(): Promise<HelloResponse>;
     resolvePath(provider: string, resource: string): Promise<ResolvePathResult>;
     bind(input: BindRequestBody): Promise<BindResult>;

package/dist/client.js

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process';
-import { request } from 'node:http';
+import { existsSync, readFileSync, readdirSync, readlinkSync } from 'node:fs';
+import { request, } from 'node:http';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 /**
@@ -16,11 +17,12 @@ import { join } from 'node:path';
 /** Control-plane API version this client speaks. Bump when adding required endpoint support. */
 export const RELAYFILE_API_VERSION = 3;
 /**
- * Minimum `relayfile` daemon version this client requires. The control-plane
- * first shipped in 0.10.17, so anything that answers `/v1/hello` is already >=
- * this — API compatibility is enforced by RELAYFILE_API_VERSION.
+ * Minimum `relayfile` daemon version this client requires. API compatibility is
+ * enforced independently through supportedApiVersions.
  */
 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 SEMVER_RE = /^\d+\.\d+\.\d+(?:[-+].*)?$/;
 /** First semver-looking token in a string (tolerates a leading `v` and surrounding words). */
 export function firstSemver(value) {
@@ -68,14 +70,36 @@ function relayfileBinary() {
 export class RelayfileControlPlaneError extends Error {
     code;
     status;
-    constructor(code, message, status) {
+    transient;
+    constructor(code, message, status, 
+    /** True only for connection failures that may clear while a daemon starts. */
+    transient = false) {
         super(message);
         this.code = code;
         this.status = status;
+        this.transient = transient;
         this.name = 'RelayfileControlPlaneError';
     }
 }
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const TRANSIENT_CONNECTION_CODES = new Set([
+    'ENOENT',
+    'ECONNREFUSED',
+    'ETIMEDOUT',
+    // A daemon that binds the socket before it is ready to serve can accept and
+    // then drop the connection mid-request; both surface during startup polling.
+    'ECONNRESET',
+    'EPIPE',
+]);
+function isTransientConnectionCode(code) {
+    return code != null && TRANSIENT_CONNECTION_CODES.has(code);
+}
+function isTransientControlPlaneError(err) {
+    return (err instanceof RelayfileControlPlaneError && err.code === 'DAEMON_UNAVAILABLE' && err.transient);
+}
+function shellQuote(value) {
+    return /^[A-Za-z0-9_./:@%+=,-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+}
 export class RelayfileControlPlaneClient {
     socketPath;
     binary;
@@ -90,6 +114,9 @@ export class RelayfileControlPlaneClient {
         this.startTimeoutMs = options.startTimeoutMs ?? 5000;
         this.requestTimeoutMs = options.requestTimeoutMs ?? 10000;
     }
+    createHTTPRequest(options, onResponse) {
+        return request(options, onResponse);
+    }
     /** Low-level request over the unix socket. Throws RelayfileControlPlaneError. */
     rawRequest(opts) {
         const query = opts.query
@@ -114,13 +141,18 @@ export class RelayfileControlPlaneClient {
                 settled = true;
                 resolve(value);
             };
-            const req = request({
+            const req = this.createHTTPRequest({
                 socketPath: this.socketPath,
                 method: opts.method,
                 path,
                 timeout: this.requestTimeoutMs,
+                // Discovery must open a fresh socket. A pooled keep-alive connection
+                // would keep reaching the unlinked stale daemon after replacement.
+                agent: opts.freshConnection ? false : undefined,
                 headers: {
-                    'X-Relayfile-API-Version': String(RELAYFILE_API_VERSION),
+                    ...(opts.includeVersionHeader === false
+                        ? {}
+                        : { 'X-Relayfile-API-Version': String(RELAYFILE_API_VERSION) }),
                     Accept: 'application/json',
                     ...(payload
                         ? { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) }
@@ -129,7 +161,7 @@ export class RelayfileControlPlaneClient {
             }, (res) => {
                 // The response stream can emit 'error' (e.g. socket reset mid-body);
                 // without a listener that's an unhandled error -> crash.
-                res.on('error', (err) => fail(new RelayfileControlPlaneError('DAEMON_UNAVAILABLE', err.message)));
+                res.on('error', (err) => fail(new RelayfileControlPlaneError('DAEMON_UNAVAILABLE', err.message, undefined, isTransientConnectionCode(err.code))));
                 const chunks = [];
                 res.on('data', (c) => chunks.push(c));
                 res.on('end', () => {
@@ -152,7 +184,7 @@ export class RelayfileControlPlaneClient {
                 });
             });
             req.on('timeout', () => {
-                req.destroy(new RelayfileControlPlaneError('DAEMON_UNAVAILABLE', `relayfile control-plane request timed out after ${this.requestTimeoutMs}ms (${opts.method} ${opts.path})`));
+                req.destroy(new RelayfileControlPlaneError('DAEMON_UNAVAILABLE', `relayfile control-plane request timed out after ${this.requestTimeoutMs}ms (${opts.method} ${opts.path})`, undefined, true));
             });
             req.on('error', (err) => {
                 if (err instanceof RelayfileControlPlaneError) {
@@ -162,7 +194,7 @@ export class RelayfileControlPlaneClient {
                 // ENOENT (no socket file) / ECONNREFUSED (nothing listening) => daemon down.
                 fail(new RelayfileControlPlaneError('DAEMON_UNAVAILABLE', err.code === 'ENOENT' || err.code === 'ECONNREFUSED'
                     ? `relayfile control-plane is not running at ${this.socketPath} (${err.code})`
-                    : err.message, undefined));
+                    : err.message, undefined, isTransientConnectionCode(err.code)));
             });
             if (payload)
                 req.write(payload);
@@ -186,7 +218,10 @@ export class RelayfileControlPlaneClient {
             hello = await this.hello();
         }
         catch (err) {
-            if (!(err instanceof RelayfileControlPlaneError) || err.code !== 'DAEMON_UNAVAILABLE')
+            if (err instanceof RelayfileControlPlaneError && err.code === 'VERSION_INCOMPATIBLE') {
+                throw await this.versionRejectionError(err);
+            }
+            if (!isTransientControlPlaneError(err))
                 throw err;
             if (!this.autoStart) {
                 throw new RelayfileControlPlaneError('DAEMON_UNAVAILABLE', `relayfile control-plane is not running at ${this.socketPath}. ` +
@@ -195,15 +230,34 @@ export class RelayfileControlPlaneClient {
             hello = await this.startDaemonAndConnect();
         }
         if (!hello.supportedApiVersions?.includes(RELAYFILE_API_VERSION)) {
-            throw new RelayfileControlPlaneError('VERSION_INCOMPATIBLE', `relayfile daemon speaks API v${hello.apiVersion} (supports ${hello.supportedApiVersions?.join(', ') || 'none'}); this client needs v${RELAYFILE_API_VERSION}. Upgrade relayfile (or agent-relay).`);
+            const installedVersion = await this.installedBinaryVersion();
+            const daemonVersion = firstSemver(hello.daemonVersion);
+            const canReplaceStaleDaemon = this.autoStart &&
+                installedVersion != null &&
+                daemonVersion !== '' &&
+                compareSemver(installedVersion, MIN_RELAYFILE_VERSION_FOR_CURRENT_API) >= 0 &&
+                compareSemver(installedVersion, daemonVersion) > 0;
+            if (!canReplaceStaleDaemon) {
+                throw this.versionMismatchError(hello, installedVersion);
+            }
+            try {
+                await this.stopStaleDaemon();
+                hello = await this.startDaemonAndConnect(installedVersion);
+            }
+            catch (err) {
+                if (err instanceof RelayfileControlPlaneError && err.code === 'VERSION_INCOMPATIBLE') {
+                    throw err;
+                }
+                throw this.versionMismatchError(hello, installedVersion, `Automatic stale-daemon replacement failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
         }
         assertRelayfileVersion(hello.daemonVersion);
     }
-    async startDaemonAndConnect() {
-        let child;
+    spawnDaemon() {
         // A missing binary / bad RELAYFILE_BIN surfaces as an async 'error' event on
         // the child (ENOENT), not a throw from spawn().
         let spawnError;
+        let child;
         try {
             child = spawn(this.binary, ['control-plane', 'serve', '--sock', this.socketPath], {
                 detached: true,
@@ -212,33 +266,223 @@ export class RelayfileControlPlaneClient {
             child.on('error', (err) => {
                 spawnError = err;
             });
+            child.once('exit', (code, signal) => {
+                spawnError = new Error(`relayfile control-plane exited before readiness (${signal ? `signal ${signal}` : `code ${code}`})`);
+            });
         }
         catch (err) {
             throw new RelayfileControlPlaneError('DAEMON_UNAVAILABLE', `failed to start relayfile control-plane (${err instanceof Error ? err.message : String(err)}). ` +
                 `Install relayfile or set RELAYFILE_BIN.`);
         }
         child.unref?.();
+        return { getError: () => spawnError };
+    }
+    async startDaemonAndConnect(installedVersion) {
+        const spawned = this.spawnDaemon();
         const deadline = Date.now() + this.startTimeoutMs;
         let lastErr;
         while (Date.now() < deadline) {
+            const spawnError = spawned.getError();
             if (spawnError) {
                 throw new RelayfileControlPlaneError('DAEMON_UNAVAILABLE', `failed to start relayfile control-plane (${spawnError.message}). ` +
                     `Install relayfile or set RELAYFILE_BIN.`);
             }
             await sleep(100);
+            let hello;
             try {
-                return await this.hello();
+                hello = await this.hello();
             }
             catch (err) {
+                if (err instanceof RelayfileControlPlaneError && err.code === 'VERSION_INCOMPATIBLE') {
+                    throw await this.versionRejectionError(err, installedVersion);
+                }
+                if (!isTransientControlPlaneError(err))
+                    throw err;
                 lastErr = err;
+                continue;
             }
+            if (hello.supportedApiVersions?.includes(RELAYFILE_API_VERSION)) {
+                return hello;
+            }
+            const mismatch = this.versionMismatchError(hello, installedVersion ?? (await this.installedBinaryVersion()));
+            throw mismatch;
         }
         throw new RelayfileControlPlaneError('DAEMON_UNAVAILABLE', `relayfile control-plane did not become ready within ${this.startTimeoutMs}ms ` +
             `(${lastErr instanceof Error ? lastErr.message : String(lastErr)}).`);
     }
+    async stopStaleDaemon() {
+        const pids = await this.socketOwnerPids();
+        if (pids.length !== 1) {
+            throw new Error(pids.length === 0
+                ? `could not identify the process serving ${this.socketPath}`
+                : `refusing to stop multiple processes serving ${this.socketPath}: ${pids.join(', ')}`);
+        }
+        try {
+            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)}`);
+        }
+        const deadline = Date.now() + this.startTimeoutMs;
+        while (existsSync(this.socketPath) && 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`);
+        }
+    }
+    async socketOwnerPids() {
+        if (process.platform === 'linux') {
+            const procPids = this.linuxSocketOwnerPids();
+            if (procPids.length > 0)
+                return procPids;
+        }
+        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);
+        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); ` +
+                `install lsof or stop the stale relayfile control-plane manually`);
+        }
+        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()}` : ''})`);
+        }
+        return [
+            ...new Set(result.stdout
+                .split(/\s+/)
+                .map((value) => Number.parseInt(value, 10))
+                .filter((pid) => Number.isSafeInteger(pid) && pid > 1 && pid !== process.pid)),
+        ];
+    }
+    /** Resolve a Unix-socket owner without external tools on standard Linux hosts. */
+    linuxSocketOwnerPids(procRoot = '/proc') {
+        let socketInodes;
+        try {
+            socketInodes = new Set(readFileSync(join(procRoot, 'net', 'unix'), 'utf8')
+                .split('\n')
+                .slice(1)
+                .map((line) => line.trim().split(/\s+/))
+                .filter((fields) => fields.length >= 8 && fields.slice(7).join(' ') === this.socketPath)
+                .map((fields) => fields[6]));
+        }
+        catch {
+            return [];
+        }
+        if (socketInodes.size === 0)
+            return [];
+        const pids = new Set();
+        let processes;
+        try {
+            processes = readdirSync(procRoot).filter((name) => /^\d+$/.test(name));
+        }
+        catch {
+            return [];
+        }
+        for (const processName of processes) {
+            const pid = Number.parseInt(processName, 10);
+            if (pid <= 1 || pid === process.pid)
+                continue;
+            const fdDir = join(procRoot, processName, 'fd');
+            let descriptors;
+            try {
+                descriptors = readdirSync(fdDir);
+            }
+            catch {
+                continue;
+            }
+            for (const descriptor of descriptors) {
+                try {
+                    const target = readlinkSync(join(fdDir, descriptor));
+                    const inode = target.match(/^socket:\[(\d+)\]$/)?.[1];
+                    if (inode && socketInodes.has(inode)) {
+                        pids.add(pid);
+                        break;
+                    }
+                }
+                catch {
+                    // File descriptors may disappear while /proc is scanned.
+                }
+            }
+        }
+        return [...pids];
+    }
+    versionMismatchError(hello, installedVersion, detail) {
+        const supported = hello.supportedApiVersions?.length
+            ? hello.supportedApiVersions.map((version) => `v${version}`).join(', ')
+            : 'none reported';
+        return new RelayfileControlPlaneError('VERSION_INCOMPATIBLE', `relayfile daemon ${hello.daemonVersion} speaks API v${hello.apiVersion} ` +
+            `(supports ${supported}); this client requires API v${RELAYFILE_API_VERSION}. ` +
+            `Installed relayfile binary: ${installedVersion ?? 'version unknown'}. ` +
+            `${detail ? `${detail} ` : ''}` +
+            `Upgrade with \`npm install -g relayfile@latest\`, then restart the running control-plane with ` +
+            `\`${this.restartCommand()}\`.`);
+    }
+    async versionRejectionError(err, installedVersion) {
+        installedVersion ??= await this.installedBinaryVersion();
+        const spoken = err.message.match(/speaks API v(\d+)/i)?.[1];
+        return new RelayfileControlPlaneError('VERSION_INCOMPATIBLE', `relayfile daemon version unknown (discovery hello was rejected) speaks API ` +
+            `${spoken ? `v${spoken}` : 'version unknown'} (supported versions were not reported); ` +
+            `this client requires API v${RELAYFILE_API_VERSION}. Installed relayfile binary: ` +
+            `${installedVersion ?? 'version unknown'}. Upgrade with \`npm install -g relayfile@latest\`, ` +
+            `then restart the running control-plane with \`${this.restartCommand()}\`. ` +
+            `Daemon response: ${err.message}`, err.status);
+    }
+    restartCommand() {
+        const socket = shellQuote(this.socketPath);
+        return (`kill $(lsof -t -- ${socket}) && ` +
+            `${shellQuote(this.binary)} control-plane serve --sock ${socket}`);
+    }
+    async installedBinaryVersion() {
+        const result = await this.runCommand(this.binary, ['--version'], Math.min(this.requestTimeoutMs, 2000));
+        return firstSemver(`${result?.stdout ?? ''} ${result?.stderr ?? ''}`) || undefined;
+    }
+    runCommand(command, args, timeoutMs) {
+        return new Promise((resolve) => {
+            let child;
+            try {
+                child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+            }
+            catch {
+                resolve(undefined);
+                return;
+            }
+            let stdout = '';
+            let stderr = '';
+            let settled = false;
+            let timeout;
+            const finish = (result) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timeout)
+                    clearTimeout(timeout);
+                resolve(result);
+            };
+            child.stdout?.on('data', (chunk) => {
+                stdout += String(chunk);
+            });
+            child.stderr?.on('data', (chunk) => {
+                stderr += String(chunk);
+            });
+            child.once('error', () => finish());
+            child.once('close', (code) => finish({ stdout, stderr, code }));
+            timeout = setTimeout(() => {
+                child.kill();
+                finish();
+            }, timeoutMs);
+            timeout.unref?.();
+        });
+    }
     // ── endpoints ──────────────────────────────────────────────────────────────
     hello() {
-        return this.rawRequest({ method: 'GET', path: '/v1/hello' });
+        return this.rawRequest({
+            method: 'GET',
+            path: '/v1/hello',
+            includeVersionHeader: false,
+            freshConnection: true,
+        });
     }
     resolvePath(provider, resource) {
         return this.request({

package/dist/generated/control-plane.d.ts

@@ -10,7 +10,14 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Negotiate control-plane API compatibility */
+        /**
+         * Negotiate control-plane API compatibility
+         * @description Unversioned discovery endpoint. The daemon always returns its current
+         *     and supported API versions; any version header or query is ignored.
+         *     No version parameters are declared here on purpose: discovery must stay
+         *     callable by clients of any API version, including versions this contract
+         *     does not know about.
+         */
         get: operations["hello"];
         put?: never;
         /** Negotiate control-plane API compatibility */
@@ -366,7 +373,6 @@ export interface components {
     };
     parameters: {
         ApiVersionHeader: 3;
-        ApiVersionQuery: number;
     };
     requestBodies: never;
     headers: never;
@@ -376,12 +382,8 @@ export type $defs = Record<string, never>;
 export interface operations {
     hello: {
         parameters: {
-            query?: {
-                apiVersion?: components["parameters"]["ApiVersionQuery"];
-            };
-            header?: {
-                "X-Relayfile-API-Version"?: components["parameters"]["ApiVersionHeader"];
-            };
+            query?: never;
+            header?: never;
             path?: never;
             cookie?: never;
         };
@@ -396,7 +398,6 @@ export interface operations {
                     "application/json": components["schemas"]["HelloResponse"];
                 };
             };
-            426: components["responses"]["VersionIncompatible"];
         };
     };
     helloPost: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/client",
-  "version": "0.10.26",
+  "version": "0.10.27",
   "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",