unitup 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-10-18
+
+### Added
+- **Supervisor Active Generation TCP Health Verification & Self-Healing**: Supervisor now validates TCP connectivity on the internal port (`active.internalPort`) of persisted active generations at startup. If the target generation is dead or refusing connections, supervisor cleans up stale state and automatically triggers a fresh deployment, eliminating stale `502 Bad Gateway (ECONNREFUSED)` loops.
+- **Systemd Crash Loop Circuit Breaker (`RestartPreventExitStatus=78`)**: Added `RestartPreventExitStatus=78` (POSIX `EX_CONFIG`) to generated systemd unit files, paired with `StartLimitIntervalSec=30s` and `StartLimitBurst=5`. When supervisor encounters unrecoverable configuration errors (such as public port collision / `EADDRINUSE`), it exits with code 78, preventing systemd from endlessly restarting and spamming journald logs.
+- **Enhanced Connection Diagnostics in Router**: Detailed internal port and error context (`connect ECONNREFUSED 127.0.0.1:<port>`) reported on proxy failures to clarify application startup crashes.
+- **Exported `IPCClient` Type Definitions**: Exported `IPCClient` class and interface in `index.d.ts` for clean downstream programmatic integration by orchestrators.
+
+### Fixed
+- **Systemd Unit Parser & Directives**: Added extraction and preservation of `RestartPreventExitStatus` in `parseUnitContent` to maintain parity across read/write cycles.
+- **Router In-Flight Request Timing**: Resolved timing race condition in `test/router.test.js` in-flight request tracking test.
+
 ## [0.4.0] - 2026-10-18
 
 ### Added

package/index.d.ts

@@ -688,6 +688,12 @@ export class RollbackManager {
   ): Promise<RollbackResult>;
 }
 
+export class IPCClient {
+  constructor(serviceName: string, ipcDir?: string);
+  isAlive(): Promise<boolean>;
+  send(message: Record<string, unknown>, onProgress?: (msg: unknown) => void, timeoutMs?: number): Promise<unknown>;
+}
+
 export class Supervisor {
   constructor(serviceName: string, serviceConfig?: Record<string, unknown>, options?: Record<string, unknown>);
   start(): Promise<Supervisor>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitup",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Minimal, zero-dependency cross-platform native service manager (systemd, launchd, Windows Services) for any runtime, script, or executable",
   "main": "src/index.js",
   "types": "./index.d.ts",

package/src/core/router.js

@@ -385,7 +385,11 @@ export class Router {
       cleanupInFlight();
       if (!res.headersSent) {
         res.writeHead(502, { 'Content-Type': 'text/plain; charset=utf-8' });
-        res.end(`502 Bad Gateway: Error communicating with generation #${genId} (${err.message}).`);
+        const errorDetail =
+          err.code === 'ECONNREFUSED'
+            ? `Connection refused at 127.0.0.1:${backend.internalPort}. The application process may have crashed or not bound to process.env.PORT.`
+            : err.message;
+        res.end(`502 Bad Gateway: Error communicating with generation #${genId} (${errorDetail}).`);
       } else {
         res.destroy();
       }

package/src/core/supervisor.js

@@ -146,12 +146,25 @@ export class Supervisor {
 
     // 3. Check if there is an active running generation from persisted state
     const active = this.generationManager.getActive(this.serviceName);
+    let activeHealthy = false;
     if (active && this.processManager.isAlive(active.pid)) {
-      if (publicPort) {
-        await this.router.listen(publicPort, '0.0.0.0', this.serviceName);
+      // Verify internal port is actually listening to prevent 502 Bad Gateway
+      activeHealthy = await this.readiness.checkTcp(active.internalPort, '127.0.0.1', 1000);
+      if (activeHealthy) {
+        if (publicPort) {
+          await this.router.listen(publicPort, '0.0.0.0', this.serviceName);
+        }
+        this.router.switchBackend(this.serviceName, active, publicPort);
+      }
+    }
+
+    if (!activeHealthy) {
+      if (active) {
+        process.stderr.write(
+          `[unitup supervisor] Persisted active generation #${active.id} (PID ${active.pid}) is not listening on internal port :${active.internalPort}. Deploying fresh instance...\n`
+        );
+        this.generationManager.remove(active, false);
       }
-      this.router.switchBackend(this.serviceName, active, publicPort);
-    } else {
       // Start initial generation
       await this.deploymentManager.deploy(this.serviceName, this.config, {
         publicPort,
@@ -216,7 +229,11 @@ export class Supervisor {
       await supervisor.start();
     } catch (err) {
       process.stderr.write(`[unitup supervisor] Failed to start: ${err.message}\n`);
-      process.exit(1);
+      const isUnrecoverableConfigError =
+        err.message?.includes('already occupied') ||
+        err.message?.includes('EADDRINUSE') ||
+        err.name === 'PortMismatchError';
+      process.exit(isUnrecoverableConfigError ? 78 : 1);
     }
   }
 }

package/src/unit.js

@@ -107,6 +107,8 @@ export function generateUnitContent(opts) {
     '[Unit]',
     `Description=unitup service: ${safeName}`,
     'After=network.target',
+    'StartLimitIntervalSec=30s',
+    'StartLimitBurst=5',
     '',
     '[Service]',
     'Type=simple',
@@ -115,6 +117,7 @@ export function generateUnitContent(opts) {
     `ExecStart=${execStartLine}`,
     `Restart=${restartPolicy}`,
     'RestartSec=3',
+    'RestartPreventExitStatus=78',
     'StandardOutput=journal',
     'StandardError=journal',
     `LogLevelMax=${logLevelMax}`,
@@ -266,6 +269,8 @@ export function parseUnitContent(content) {
       }
     } else if (trimmed.startsWith('Restart=')) {
       result.restart = trimmed.slice(8).trim();
+    } else if (trimmed.startsWith('RestartPreventExitStatus=')) {
+      result.restartPreventExitStatus = trimmed.slice(25).trim();
     } else if (trimmed.startsWith('MemoryHigh=')) {
       result.memoryHigh = trimmed.slice(11).trim();
     } else if (trimmed.startsWith('MemoryMax=')) {