livedesk 0.1.250 → 0.1.251

package/README.md

@@ -16,10 +16,12 @@ continues to listen on the LAN.
 On startup, the launcher finds stale processes whose command line identifies
 them as a LiveDesk Hub, even if the old Hub is still starting and has not
 finished binding its ports. It also checks the Hub ports (`5179` and `5197`),
-waits for the old process and both ports to be released, and then starts the
-new Hub. An unrelated process is preserved and reported instead of being
-terminated; use `--port`, `--remote-port`, or stop that process manually. Pass
-`--no-clean` to disable the startup cleanup explicitly.
+waits for stale LiveDesk processes to exit, and then starts the new Hub. An
+unrelated process is preserved and reported instead of being terminated. If
+the client port remains occupied, the Hub automatically retries on a nearby
+port and publishes that actual endpoint to clients. The HTTP manager port
+remains strict so a web UI collision is reported clearly. Pass `--no-clean` to
+disable the startup cleanup explicitly.
 
 ## Client
 

package/bin/livedesk.js

@@ -37,7 +37,8 @@ Hub options:
   --host <host>  Hub HTTP host. Default: 127.0.0.1
   --port <port>  Hub HTTP port. Default: 5179
   --remote-port <port>
-                 Client connection port. Default: 5197
+                 Preferred client connection port. Default: 5197; if busy,
+                 LiveDesk retries on a nearby port automatically.
   --no-clean     Do not stop existing processes on the Hub ports.
 
 Common:
@@ -212,7 +213,7 @@ function runQuiet(command, args) {
   });
 }
 
-async function stopProcessesOnPorts(ports) {
+async function stopProcessesOnPorts(ports, { allowBusyPorts = false } = {}) {
   const uniquePorts = [...new Set(ports.map(port => normalizePort(port, 0)).filter(Boolean))];
   if (uniquePorts.length === 0) {
     return;
@@ -292,7 +293,11 @@ async function stopProcessesOnPorts(ports) {
     const blocked = records.filter(record => record?.PortAvailable !== true || (record?.Port === 0 && record?.ProcessGone !== true));
     if (blocked.length > 0) {
       const summary = blocked.map(record => `${record.Pid}:${record.ProcessName || 'unknown'}@${record.Port}[port-free=${record.PortAvailable === true},process-gone=${record.ProcessGone === true}]`).join(', ');
-      throw new Error(`LiveDesk Hub startup cleanup could not release port/process owner(s): ${summary}. If this is an unrelated process, use --port/--remote-port or stop it manually.`);
+      const message = `LiveDesk Hub startup cleanup could not release port/process owner(s): ${summary}`;
+      if (!allowBusyPorts) {
+        throw new Error(`${message}. If this is an unrelated process, use --port or stop it manually.`);
+      }
+      console.warn(`${message}. The client endpoint will retry on another port automatically.`);
     }
     return;
   }
@@ -350,7 +355,8 @@ async function runManager(args) {
     || getStablePairToken();
 
   if (options.cleanPortsOnStart) {
-    await stopProcessesOnPorts([httpPort, remotePort]);
+    await stopProcessesOnPorts([httpPort]);
+    await stopProcessesOnPorts([remotePort], { allowBusyPorts: true });
   }
 
   const internalHubEntry = resolve(packageRoot, 'hub', 'src', 'server.js');

package/hub/src/remote-hub.js

@@ -4,6 +4,8 @@ import crypto from 'crypto';
 
 const DEFAULT_REMOTE_HUB_PORT = 5197;
 const DEFAULT_REMOTE_HUB_HOST = '0.0.0.0';
+const DEFAULT_REMOTE_HUB_PORT_FALLBACK_ATTEMPTS = 32;
+const REMOTE_HUB_AUTH_CALLBACK_PORT = 5198;
 const DEFAULT_HEARTBEAT_MS = 5000;
 const DEFAULT_AGENT_TASK_TIMEOUT_MS = 120000;
 const MAX_LINE_CHARS = 4 * 1024 * 1024;
@@ -1417,6 +1419,14 @@ export function createRemoteHub(options = {}) {
         && !isDisabledValue(env.REMOTE_HUB_DISABLED);
     const host = safeString(env.REMOTE_HUB_HOST || DEFAULT_REMOTE_HUB_HOST, 128);
     const requestedPort = normalizePort(env.REMOTE_HUB_PORT || DEFAULT_REMOTE_HUB_PORT);
+    const remotePortFallbackEnabled = isEnabledValue(env.REMOTE_HUB_PORT_FALLBACK, true)
+        && !isDisabledValue(env.REMOTE_HUB_PORT_FALLBACK_DISABLED);
+    const remotePortFallbackStrict = isEnabledValue(env.REMOTE_HUB_PORT_FALLBACK_STRICT, false);
+    const remotePortFallbackAttempts = clampNumber(
+        env.REMOTE_HUB_PORT_FALLBACK_ATTEMPTS,
+        1,
+        128,
+        DEFAULT_REMOTE_HUB_PORT_FALLBACK_ATTEMPTS);
     const heartbeatMs = clampNumber(env.REMOTE_HUB_HEARTBEAT_MS, 1000, 60000, DEFAULT_HEARTBEAT_MS);
     const taskTimeoutMs = clampNumber(
         options.taskTimeoutMs ?? env.REMOTE_HUB_TASK_TIMEOUT_MS,
@@ -4371,21 +4381,31 @@ export function createRemoteHub(options = {}) {
         });
     }
 
-    async function start() {
-        if (!enabled || started) {
-            return getStatus({ includeSecrets: false });
+    function getNextFallbackPort(currentPort, attemptedPorts) {
+        for (let offset = 1; offset <= 65535; offset += 1) {
+            const candidate = (currentPort + offset) % 65536;
+            if (candidate < 1 || candidate === REMOTE_HUB_AUTH_CALLBACK_PORT || attemptedPorts.has(candidate)) {
+                continue;
+            }
+            return candidate;
         }
+        return 0;
+    }
 
-        await new Promise((resolve, reject) => {
-            server = net.createServer(handleSocket);
-            server.once('error', err => {
+    function listenOnPort(port) {
+        return new Promise((resolve, reject) => {
+            const candidateServer = net.createServer(handleSocket);
+            server = candidateServer;
+            candidateServer.once('error', err => {
                 lastError = err?.message || String(err);
-                server = null;
+                if (server === candidateServer) {
+                    server = null;
+                }
                 reject(err);
             });
-            server.listen(requestedPort, host, () => {
+            candidateServer.listen(port, host, () => {
                 started = true;
-                boundPort = server.address()?.port || requestedPort;
+                boundPort = candidateServer.address()?.port || port;
                 lastError = '';
                 logEvent('remote', `LiveDesk Hub client endpoint listening on tcp://${host}:${boundPort}`, 'success');
                 if (host === '0.0.0.0' || host === '::') {
@@ -4395,6 +4415,48 @@ export function createRemoteHub(options = {}) {
                 resolve();
             });
         });
+    }
+
+    async function start() {
+        if (!enabled || started) {
+            return getStatus({ includeSecrets: false });
+        }
+
+        const fallbackAllowed = remotePortFallbackEnabled
+            && !remotePortFallbackStrict
+            && requestedPort > 0;
+        const attemptedPorts = new Set();
+        let candidatePort = requestedPort;
+        let lastBindError = null;
+
+        for (let attempt = 0; attempt < remotePortFallbackAttempts; attempt += 1) {
+            attemptedPorts.add(candidatePort);
+            try {
+                await listenOnPort(candidatePort);
+                if (candidatePort !== requestedPort) {
+                    logWarn(
+                        'remote',
+                        `Client port ${requestedPort} is already in use; LiveDesk Hub is using ${candidatePort}.`);
+                }
+                lastBindError = null;
+                break;
+            } catch (error) {
+                lastBindError = error;
+                if (error?.code !== 'EADDRINUSE' || !fallbackAllowed) {
+                    throw error;
+                }
+
+                const nextPort = getNextFallbackPort(candidatePort, attemptedPorts);
+                if (!nextPort) {
+                    break;
+                }
+                candidatePort = nextPort;
+            }
+        }
+
+        if (lastBindError) {
+            throw lastBindError;
+        }
 
         return getStatus({ includeSecrets: false });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "livedesk",
-  "version": "0.1.250",
+  "version": "0.1.251",
   "description": "LiveDesk Hub and client launcher",
   "type": "module",
   "bin": {