@relayfile/client 0.10.26 → 0.10.27-rc.0

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'];
@@ -80,7 +83,14 @@ export declare class RelayfileControlPlaneClient {
     /** Connect (auto-starting the daemon if configured), version-negotiating once. */
     ensureReady(): Promise<void>;
     private connectAndNegotiate;
+    private spawnDaemon;
     private startDaemonAndConnect;
+    private stopStaleDaemon;
+    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,4 +1,5 @@
 import { spawn } from 'node:child_process';
+import { existsSync } 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,28 @@ 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']);
+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;
@@ -119,8 +135,13 @@ export class RelayfileControlPlaneClient {
                 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 +150,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 +173,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 +183,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 +207,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 +219,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 +255,152 @@ 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 result = await this.runCommand('lsof', ['-t', '--', this.socketPath], 1000);
+        const pids = [
+            ...new Set((result?.code === 0 ? result.stdout : '')
+                .split(/\s+/)
+                .map((value) => Number.parseInt(value, 10))
+                .filter((pid) => Number.isSafeInteger(pid) && pid > 1 && pid !== process.pid)),
+        ];
+        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`);
+        }
+    }
+    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,11 @@ 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.
+         */
         get: operations["hello"];
         put?: never;
         /** Negotiate control-plane API compatibility */
@@ -396,7 +400,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-rc.0",
   "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",