@iskra-bun/process-kit 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @iskra-bun/process-kit
 
+## 0.2.0
+
+### Minor Changes
+
+- f9654df: New process-management features:
+
+    - `spawn(name, config)` and `kill(name)` to add or gracefully remove individual processes at runtime, instead of only at boot.
+    - Configurable exponential restart backoff (`restartBackoff: { initialMs, maxMs, factor }` on `ProcessConfig`) replacing the fixed 1s restart delay, so a crash-looping process backs off instead of hammering a broken dependency. Defaults to the previous 1s when unset.
+
+### Patch Changes
+
+- f9654df: `stop()` now shuts processes down gracefully — SIGTERM, wait for exit with a configurable timeout, then SIGKILL — and awaits exit before clearing state. `oneshot` mode is now implemented: the process runs to completion once and is never restarted, even when `restartOnCrash` is set.
+- `terminate()` now detects orphaned processes: when a process survives both SIGTERM and SIGKILL, it logs an error (`survived SIGTERM and SIGKILL and is now an orphan`) via `app.logger` instead of failing silently. This is shared by `kill()` and `stop()`; a process that exits cleanly does not log.
+- Updated dependencies [f9654df]
+- Updated dependencies
+- Updated dependencies [f9654df]
+    - @iskra-bun/core@0.1.1
+
 ## 0.1.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Driver, App } from '@iskra-bun/core';
+import { Driver, App, ProcessConfig } from '@iskra-bun/core';
 
 declare class ProcessManager implements Driver {
     name: string;
@@ -7,13 +7,48 @@ declare class ProcessManager implements Driver {
     private stopping;
     init(app: App): void;
     start(): Promise<void>;
+    /**
+     * Spawn and register a new process at runtime. Reuses the existing internal
+     * spawn logic and respects the process mode (stdio/daemon/oneshot).
+     *
+     * @throws {Error} if a process with the given name is already registered.
+     */
+    spawn(name: string, config: ProcessConfig): Promise<void>;
+    /**
+     * Gracefully stop and remove a single named process. Sends SIGTERM, then
+     * escalates to SIGKILL after `gracefulTimeoutMs`. The worst-case wait before
+     * this method resolves is `gracefulTimeoutMs * 2`: `gracefulTimeoutMs` for the
+     * SIGKILL escalation plus another `gracefulTimeoutMs` grace window for the
+     * process to actually exit afterwards. If the process still has not exited by
+     * then, it is reported as an orphan via `app.logger.error`.
+     *
+     * @throws {Error} if no process with the given name exists.
+     */
+    kill(name: string, gracefulTimeoutMs?: number): Promise<void>;
+    /**
+     * Send SIGTERM, escalate to SIGKILL after `gracefulTimeoutMs`, and wait up to
+     * `gracefulTimeoutMs * 2` for the process to exit. After the race settles, if
+     * the process is still alive it is surfaced as an orphan via `app.logger.error`
+     * so a hung shutdown is observable instead of silently succeeding.
+     */
+    private terminate;
     private readStdOut;
     private processLine;
+    /**
+     * Compute the next backoff delay for a process restart.
+     *
+     * - If no `restartBackoff` config is provided, returns the flat 1000 ms default.
+     * - The FIRST restart (`restarts === 0`) waits exactly `currentBackoffMs`
+     *   (seeded to `initialMs` on spawn); exponential growth begins on the SECOND
+     *   restart with `min(currentMs * factor, maxMs)`.
+     * - If the process was stable (uptime > restartCooldown), the backoff resets to initialMs.
+     */
+    private computeBackoffMs;
     private handleExit;
     private spawnProcess;
     private readStdErr;
     send(name: string, data: any): Promise<void>;
-    stop(): Promise<void>;
+    stop(gracefulTimeoutMs?: number): Promise<void>;
 }
 
 export { ProcessManager };

package/dist/index.js

@@ -19,6 +19,68 @@ var ProcessManager = class {
       this.spawnProcess(name, config);
     }
   }
+  /**
+   * Spawn and register a new process at runtime. Reuses the existing internal
+   * spawn logic and respects the process mode (stdio/daemon/oneshot).
+   *
+   * @throws {Error} if a process with the given name is already registered.
+   */
+  async spawn(name, config) {
+    if (this.processes.has(name)) {
+      throw new Error(`Process '${name}' is already registered. Kill it first or use a different name.`);
+    }
+    this.spawnProcess(name, config);
+  }
+  /**
+   * Gracefully stop and remove a single named process. Sends SIGTERM, then
+   * escalates to SIGKILL after `gracefulTimeoutMs`. The worst-case wait before
+   * this method resolves is `gracefulTimeoutMs * 2`: `gracefulTimeoutMs` for the
+   * SIGKILL escalation plus another `gracefulTimeoutMs` grace window for the
+   * process to actually exit afterwards. If the process still has not exited by
+   * then, it is reported as an orphan via `app.logger.error`.
+   *
+   * @throws {Error} if no process with the given name exists.
+   */
+  async kill(name, gracefulTimeoutMs = 5e3) {
+    const procInfo = this.processes.get(name);
+    if (!procInfo) {
+      throw new Error(`Process '${name}' not found. It may have already exited or never been spawned.`);
+    }
+    this.processes.delete(name);
+    const proc = procInfo.process;
+    if (proc.killed) return;
+    await this.terminate(name, proc, gracefulTimeoutMs);
+  }
+  /**
+   * Send SIGTERM, escalate to SIGKILL after `gracefulTimeoutMs`, and wait up to
+   * `gracefulTimeoutMs * 2` for the process to exit. After the race settles, if
+   * the process is still alive it is surfaced as an orphan via `app.logger.error`
+   * so a hung shutdown is observable instead of silently succeeding.
+   */
+  async terminate(name, proc, gracefulTimeoutMs) {
+    proc.kill("SIGTERM");
+    const deadline = gracefulTimeoutMs * 2;
+    const forceKillTimer = setTimeout(() => {
+      if (!proc.killed) {
+        this.app?.logger.warn(`Process ${name} did not exit within ${gracefulTimeoutMs}ms; sending SIGKILL`);
+        proc.kill();
+      }
+    }, gracefulTimeoutMs);
+    try {
+      await Promise.race([
+        proc.exited,
+        new Promise((r) => setTimeout(r, deadline))
+      ]);
+    } finally {
+      clearTimeout(forceKillTimer);
+    }
+    if (!proc.killed) {
+      this.app?.logger.error(
+        { name },
+        `Process ${name} survived SIGTERM and SIGKILL and is now an orphan; manual cleanup may be required`
+      );
+    }
+  }
   async readStdOut(name, stream) {
     const reader = stream.getReader();
     const decoder = new TextDecoder();
@@ -36,6 +98,7 @@ var ProcessManager = class {
         }
       }
     } catch (err) {
+      this.app?.logger.debug({ err, name }, `stdout reader for process ${name} failed`);
     }
   }
   processLine(name, line) {
@@ -46,12 +109,44 @@ var ProcessManager = class {
       this.app?.emit("process:log", { name, text: line });
     }
   }
-  handleExit(name, exitCode, signalCode) {
+  /**
+   * Compute the next backoff delay for a process restart.
+   *
+   * - If no `restartBackoff` config is provided, returns the flat 1000 ms default.
+   * - The FIRST restart (`restarts === 0`) waits exactly `currentBackoffMs`
+   *   (seeded to `initialMs` on spawn); exponential growth begins on the SECOND
+   *   restart with `min(currentMs * factor, maxMs)`.
+   * - If the process was stable (uptime > restartCooldown), the backoff resets to initialMs.
+   */
+  computeBackoffMs(procInfo) {
+    const backoffCfg = procInfo.config.restartBackoff;
+    if (!backoffCfg) {
+      return 1e3;
+    }
+    const cooldown = procInfo.config.restartCooldown ?? 6e4;
+    const uptime = Date.now() - procInfo.startedAt;
+    if (uptime > cooldown) {
+      return backoffCfg.initialMs ?? 1e3;
+    }
+    const maxMs = backoffCfg.maxMs ?? 3e4;
+    const initialMs = backoffCfg.initialMs ?? 1e3;
+    if (procInfo.restarts === 0 && procInfo.currentBackoffMs === initialMs) {
+      return Math.min(procInfo.currentBackoffMs, maxMs);
+    }
+    const factor = backoffCfg.factor ?? 2;
+    const next = Math.min(procInfo.currentBackoffMs * factor, maxMs);
+    return next;
+  }
+  handleExit(name, exitCode) {
     if (this.stopping) return;
     const procInfo = this.processes.get(name);
     if (!procInfo) return;
     this.app?.logger.warn(`Process ${name} exited with code ${exitCode}`);
     this.processes.delete(name);
+    if (procInfo.config.mode === "oneshot") {
+      this.app?.emit("process:exit", { name, exitCode });
+      return;
+    }
     if (procInfo.config.restartOnCrash) {
       const maxRestarts = procInfo.config.maxRestarts ?? 10;
       const cooldown = procInfo.config.restartCooldown ?? 6e4;
@@ -62,15 +157,17 @@ var ProcessManager = class {
         this.app?.emit("process:max-restarts", { name, restarts: procInfo.restarts, maxRestarts });
         return;
       }
-      this.app?.logger.info(`Restarting process: ${name} (Attempt ${restarts}/${maxRestarts})`);
+      const delayMs = this.computeBackoffMs(procInfo);
+      this.app?.logger.info(`Restarting process: ${name} (Attempt ${restarts}/${maxRestarts}) in ${delayMs}ms`);
       setTimeout(() => {
-        this.spawnProcess(name, procInfo.config, restarts);
-      }, 1e3);
+        this.spawnProcess(name, procInfo.config, restarts, delayMs);
+      }, delayMs);
     }
   }
-  // Updated spawn signature to track restarts
-  spawnProcess(name, config, restarts = 0) {
+  // Updated spawn signature to track restarts and backoff state
+  spawnProcess(name, config, restarts = 0, currentBackoffMs) {
     if (this.stopping || !this.app) return;
+    const initialBackoffMs = config.restartBackoff?.initialMs ?? 1e3;
     this.app.logger.info(`Spawning process: ${name} (${config.command} ${config.args?.join(" ") || ""})`);
     try {
       const proc = Bun.spawn(
@@ -80,8 +177,8 @@ var ProcessManager = class {
           stdout: config.mode === "stdio" ? "pipe" : "inherit",
           stderr: config.mode === "stdio" ? "pipe" : "inherit",
           stdin: config.mode === "stdio" ? "pipe" : "ignore",
-          onExit: (proc2, exitCode, signalCode, error) => {
-            this.handleExit(name, exitCode || 0, signalCode || 0);
+          onExit: (_proc, exitCode, _signalCode, _error) => {
+            this.handleExit(name, exitCode || 0);
           }
         }
       );
@@ -90,7 +187,8 @@ var ProcessManager = class {
         config,
         name,
         restarts,
-        startedAt: Date.now()
+        startedAt: Date.now(),
+        currentBackoffMs: currentBackoffMs ?? initialBackoffMs
       });
       if (config.mode === "stdio") {
         if (proc.stdout) this.readStdOut(name, proc.stdout);
@@ -113,6 +211,7 @@ var ProcessManager = class {
         }
       }
     } catch (err) {
+      this.app?.logger.debug({ err, name }, `stderr reader for process ${name} failed`);
     }
   }
   // Send data to process stdin
@@ -130,20 +229,25 @@ var ProcessManager = class {
     try {
       const message = typeof data === "string" ? data : JSON.stringify(data);
       stdin.write(message + "\n");
-      stdin.flush();
+      if (typeof stdin.flush === "function") {
+        stdin.flush();
+      }
     } catch (err) {
       this.app?.logger.error({ err }, `Failed to write to process ${name}`);
     }
   }
-  async stop() {
+  async stop(gracefulTimeoutMs = 5e3) {
     this.stopping = true;
     this.app?.logger.info("Stopping all processes...");
-    for (const [name, info] of this.processes) {
-      if (!info.process.killed) {
-        info.process.kill();
-      }
-    }
+    const entries = [...this.processes.entries()];
     this.processes.clear();
+    await Promise.all(
+      entries.map(async ([name, info]) => {
+        const proc = info.process;
+        if (proc.killed) return;
+        await this.terminate(name, proc, gracefulTimeoutMs);
+      })
+    );
   }
 };
 export {

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/spawner.ts"],"sourcesContent":["import type { App, Driver, ProcessConfig } from '@iskra-bun/core';\nimport { Subprocess } from 'bun';\n\ninterface RunningProcess {\n    process: Subprocess;\n    config: ProcessConfig;\n    name: string;\n    restarts: number;\n    startedAt: number;\n}\n\nexport class ProcessManager implements Driver {\n    name = 'ProcessManager';\n    private app: App | null = null;\n    private processes: Map<string, RunningProcess> = new Map();\n    private stopping = false;\n\n    init(app: App) {\n        this.app = app;\n    }\n\n    async start() {\n        if (!this.app) return;\n        const processConfigs = this.app.config.processes;\n\n        if (!processConfigs) {\n            this.app.logger.debug('No processes configured.');\n            return;\n        }\n\n        this.app.logger.info(`Starting ${Object.keys(processConfigs).length} processes...`);\n\n        for (const [name, config] of Object.entries(processConfigs)) {\n            this.spawnProcess(name, config);\n        }\n    }\n\n    private async readStdOut(name: string, stream: ReadableStream) {\n        const reader = stream.getReader();\n        const decoder = new TextDecoder();\n        let buffer = '';\n\n        try {\n            while (true) {\n                const { done, value } = await reader.read();\n                if (done) break;\n\n                buffer += decoder.decode(value, { stream: true });\n\n                const lines = buffer.split('\\n');\n                // Keep the last chunk if it's not a complete line (doesn't end with \\n)\n                buffer = lines.pop() || '';\n\n                for (const line of lines) {\n                    if (!line.trim()) continue;\n                    this.processLine(name, line);\n                }\n            }\n        } catch (err) {\n            // Stream closed or error\n        }\n    }\n\n    private processLine(name: string, line: string) {\n        try {\n            // Try to parse as JSON Event\n            const json = JSON.parse(line);\n            this.app?.emit('process:message', { name, message: json });\n        } catch {\n            // Fallback to raw log\n            this.app?.emit('process:log', { name, text: line });\n        }\n    }\n\n    private handleExit(name: string, exitCode: number, signalCode: number) {\n        if (this.stopping) return;\n\n        const procInfo = this.processes.get(name);\n        if (!procInfo) return;\n\n        this.app?.logger.warn(`Process ${name} exited with code ${exitCode}`);\n\n        // Remove from map so we don't try to kill it again on stop()\n        this.processes.delete(name);\n\n        if (procInfo.config.restartOnCrash) {\n            const maxRestarts = procInfo.config.maxRestarts ?? 10;\n            const cooldown = procInfo.config.restartCooldown ?? 60000;\n            const uptime = Date.now() - procInfo.startedAt;\n\n            // If the process ran longer than the cooldown, consider it stable and reset the counter\n            const restarts = uptime > cooldown ? 1 : procInfo.restarts + 1;\n\n            if (restarts > maxRestarts) {\n                this.app?.logger.error(`Process ${name} exceeded max restarts (${maxRestarts}). Not restarting.`);\n                this.app?.emit('process:max-restarts', { name, restarts: procInfo.restarts, maxRestarts });\n                return;\n            }\n\n            this.app?.logger.info(`Restarting process: ${name} (Attempt ${restarts}/${maxRestarts})`);\n\n            setTimeout(() => {\n                this.spawnProcess(name, procInfo.config, restarts);\n            }, 1000);\n        }\n    }\n\n    // Updated spawn signature to track restarts\n    private spawnProcess(name: string, config: ProcessConfig, restarts = 0) {\n        if (this.stopping || !this.app) return;\n\n        this.app.logger.info(`Spawning process: ${name} (${config.command} ${config.args?.join(' ') || ''})`);\n\n        try {\n            const proc = Bun.spawn(\n                [config.command, ...(config.args || [])],\n                {\n                    env: { ...process.env, ...config.env },\n                    stdout: config.mode === 'stdio' ? 'pipe' : 'inherit',\n                    stderr: config.mode === 'stdio' ? 'pipe' : 'inherit',\n                    stdin: config.mode === 'stdio' ? 'pipe' : 'ignore',\n                    onExit: (proc, exitCode, signalCode, error) => {\n                        this.handleExit(name, exitCode || 0, signalCode || 0);\n                    }\n                }\n            );\n\n            this.processes.set(name, {\n                process: proc,\n                config,\n                name,\n                restarts,\n                startedAt: Date.now(),\n            });\n\n            if (config.mode === 'stdio') {\n                if (proc.stdout) this.readStdOut(name, proc.stdout);\n                if (proc.stderr) this.readStdErr(name, proc.stderr);\n            }\n\n        } catch (err) {\n            this.app.logger.error({ err }, `Failed to spawn process: ${name}`);\n        }\n    }\n\n    private async readStdErr(name: string, stream: ReadableStream) {\n        const reader = stream.getReader();\n        const decoder = new TextDecoder();\n\n        try {\n            while (true) {\n                const { done, value } = await reader.read();\n                if (done) break;\n                const text = decoder.decode(value, { stream: true });\n                if (text.trim()) {\n                    this.app?.emit('process:error', { name, text });\n                }\n            }\n        } catch (err) {\n            // Stream closed\n        }\n    }\n\n    // Send data to process stdin\n    async send(name: string, data: any) {\n        const procInfo = this.processes.get(name);\n        if (!procInfo) {\n            this.app?.logger.warn(`Cannot send message to non-existent process: ${name}`);\n            return;\n        }\n\n        if (procInfo.config.mode !== 'stdio' || !procInfo.process.stdin) {\n            this.app?.logger.warn(`Cannot send message to process ${name} (mode is not stdio or stdin is closed)`);\n            return;\n        }\n\n        // Bun's Subprocess.stdin is a FileSink\n        const stdin = procInfo.process.stdin as any;\n\n        try {\n            // If data is object, stringify it and add newline\n            const message = typeof data === 'string' ? data : JSON.stringify(data);\n            stdin.write(message + '\\n');\n            stdin.flush();\n        } catch (err) {\n            this.app?.logger.error({ err }, `Failed to write to process ${name}`);\n        }\n    }\n\n    async stop() {\n        this.stopping = true;\n        this.app?.logger.info('Stopping all processes...');\n\n        for (const [name, info] of this.processes) {\n            if (!info.process.killed) {\n                info.process.kill();\n            }\n        }\n        this.processes.clear();\n    }\n}\n"],"mappings":";AAWO,IAAM,iBAAN,MAAuC;AAAA,EAC1C,OAAO;AAAA,EACC,MAAkB;AAAA,EAClB,YAAyC,oBAAI,IAAI;AAAA,EACjD,WAAW;AAAA,EAEnB,KAAK,KAAU;AACX,SAAK,MAAM;AAAA,EACf;AAAA,EAEA,MAAM,QAAQ;AACV,QAAI,CAAC,KAAK,IAAK;AACf,UAAM,iBAAiB,KAAK,IAAI,OAAO;AAEvC,QAAI,CAAC,gBAAgB;AACjB,WAAK,IAAI,OAAO,MAAM,0BAA0B;AAChD;AAAA,IACJ;AAEA,SAAK,IAAI,OAAO,KAAK,YAAY,OAAO,KAAK,cAAc,EAAE,MAAM,eAAe;AAElF,eAAW,CAAC,MAAM,MAAM,KAAK,OAAO,QAAQ,cAAc,GAAG;AACzD,WAAK,aAAa,MAAM,MAAM;AAAA,IAClC;AAAA,EACJ;AAAA,EAEA,MAAc,WAAW,MAAc,QAAwB;AAC3D,UAAM,SAAS,OAAO,UAAU;AAChC,UAAM,UAAU,IAAI,YAAY;AAChC,QAAI,SAAS;AAEb,QAAI;AACA,aAAO,MAAM;AACT,cAAM,EAAE,MAAM,MAAM,IAAI,MAAM,OAAO,KAAK;AAC1C,YAAI,KAAM;AAEV,kBAAU,QAAQ,OAAO,OAAO,EAAE,QAAQ,KAAK,CAAC;AAEhD,cAAM,QAAQ,OAAO,MAAM,IAAI;AAE/B,iBAAS,MAAM,IAAI,KAAK;AAExB,mBAAW,QAAQ,OAAO;AACtB,cAAI,CAAC,KAAK,KAAK,EAAG;AAClB,eAAK,YAAY,MAAM,IAAI;AAAA,QAC/B;AAAA,MACJ;AAAA,IACJ,SAAS,KAAK;AAAA,IAEd;AAAA,EACJ;AAAA,EAEQ,YAAY,MAAc,MAAc;AAC5C,QAAI;AAEA,YAAM,OAAO,KAAK,MAAM,IAAI;AAC5B,WAAK,KAAK,KAAK,mBAAmB,EAAE,MAAM,SAAS,KAAK,CAAC;AAAA,IAC7D,QAAQ;AAEJ,WAAK,KAAK,KAAK,eAAe,EAAE,MAAM,MAAM,KAAK,CAAC;AAAA,IACtD;AAAA,EACJ;AAAA,EAEQ,WAAW,MAAc,UAAkB,YAAoB;AACnE,QAAI,KAAK,SAAU;AAEnB,UAAM,WAAW,KAAK,UAAU,IAAI,IAAI;AACxC,QAAI,CAAC,SAAU;AAEf,SAAK,KAAK,OAAO,KAAK,WAAW,IAAI,qBAAqB,QAAQ,EAAE;AAGpE,SAAK,UAAU,OAAO,IAAI;AAE1B,QAAI,SAAS,OAAO,gBAAgB;AAChC,YAAM,cAAc,SAAS,OAAO,eAAe;AACnD,YAAM,WAAW,SAAS,OAAO,mBAAmB;AACpD,YAAM,SAAS,KAAK,IAAI,IAAI,SAAS;AAGrC,YAAM,WAAW,SAAS,WAAW,IAAI,SAAS,WAAW;AAE7D,UAAI,WAAW,aAAa;AACxB,aAAK,KAAK,OAAO,MAAM,WAAW,IAAI,2BAA2B,WAAW,oBAAoB;AAChG,aAAK,KAAK,KAAK,wBAAwB,EAAE,MAAM,UAAU,SAAS,UAAU,YAAY,CAAC;AACzF;AAAA,MACJ;AAEA,WAAK,KAAK,OAAO,KAAK,uBAAuB,IAAI,aAAa,QAAQ,IAAI,WAAW,GAAG;AAExF,iBAAW,MAAM;AACb,aAAK,aAAa,MAAM,SAAS,QAAQ,QAAQ;AAAA,MACrD,GAAG,GAAI;AAAA,IACX;AAAA,EACJ;AAAA;AAAA,EAGQ,aAAa,MAAc,QAAuB,WAAW,GAAG;AACpE,QAAI,KAAK,YAAY,CAAC,KAAK,IAAK;AAEhC,SAAK,IAAI,OAAO,KAAK,qBAAqB,IAAI,KAAK,OAAO,OAAO,IAAI,OAAO,MAAM,KAAK,GAAG,KAAK,EAAE,GAAG;AAEpG,QAAI;AACA,YAAM,OAAO,IAAI;AAAA,QACb,CAAC,OAAO,SAAS,GAAI,OAAO,QAAQ,CAAC,CAAE;AAAA,QACvC;AAAA,UACI,KAAK,EAAE,GAAG,QAAQ,KAAK,GAAG,OAAO,IAAI;AAAA,UACrC,QAAQ,OAAO,SAAS,UAAU,SAAS;AAAA,UAC3C,QAAQ,OAAO,SAAS,UAAU,SAAS;AAAA,UAC3C,OAAO,OAAO,SAAS,UAAU,SAAS;AAAA,UAC1C,QAAQ,CAACA,OAAM,UAAU,YAAY,UAAU;AAC3C,iBAAK,WAAW,MAAM,YAAY,GAAG,cAAc,CAAC;AAAA,UACxD;AAAA,QACJ;AAAA,MACJ;AAEA,WAAK,UAAU,IAAI,MAAM;AAAA,QACrB,SAAS;AAAA,QACT;AAAA,QACA;AAAA,QACA;AAAA,QACA,WAAW,KAAK,IAAI;AAAA,MACxB,CAAC;AAED,UAAI,OAAO,SAAS,SAAS;AACzB,YAAI,KAAK,OAAQ,MAAK,WAAW,MAAM,KAAK,MAAM;AAClD,YAAI,KAAK,OAAQ,MAAK,WAAW,MAAM,KAAK,MAAM;AAAA,MACtD;AAAA,IAEJ,SAAS,KAAK;AACV,WAAK,IAAI,OAAO,MAAM,EAAE,IAAI,GAAG,4BAA4B,IAAI,EAAE;AAAA,IACrE;AAAA,EACJ;AAAA,EAEA,MAAc,WAAW,MAAc,QAAwB;AAC3D,UAAM,SAAS,OAAO,UAAU;AAChC,UAAM,UAAU,IAAI,YAAY;AAEhC,QAAI;AACA,aAAO,MAAM;AACT,cAAM,EAAE,MAAM,MAAM,IAAI,MAAM,OAAO,KAAK;AAC1C,YAAI,KAAM;AACV,cAAM,OAAO,QAAQ,OAAO,OAAO,EAAE,QAAQ,KAAK,CAAC;AACnD,YAAI,KAAK,KAAK,GAAG;AACb,eAAK,KAAK,KAAK,iBAAiB,EAAE,MAAM,KAAK,CAAC;AAAA,QAClD;AAAA,MACJ;AAAA,IACJ,SAAS,KAAK;AAAA,IAEd;AAAA,EACJ;AAAA;AAAA,EAGA,MAAM,KAAK,MAAc,MAAW;AAChC,UAAM,WAAW,KAAK,UAAU,IAAI,IAAI;AACxC,QAAI,CAAC,UAAU;AACX,WAAK,KAAK,OAAO,KAAK,gDAAgD,IAAI,EAAE;AAC5E;AAAA,IACJ;AAEA,QAAI,SAAS,OAAO,SAAS,WAAW,CAAC,SAAS,QAAQ,OAAO;AAC7D,WAAK,KAAK,OAAO,KAAK,kCAAkC,IAAI,yCAAyC;AACrG;AAAA,IACJ;AAGA,UAAM,QAAQ,SAAS,QAAQ;AAE/B,QAAI;AAEA,YAAM,UAAU,OAAO,SAAS,WAAW,OAAO,KAAK,UAAU,IAAI;AACrE,YAAM,MAAM,UAAU,IAAI;AAC1B,YAAM,MAAM;AAAA,IAChB,SAAS,KAAK;AACV,WAAK,KAAK,OAAO,MAAM,EAAE,IAAI,GAAG,8BAA8B,IAAI,EAAE;AAAA,IACxE;AAAA,EACJ;AAAA,EAEA,MAAM,OAAO;AACT,SAAK,WAAW;AAChB,SAAK,KAAK,OAAO,KAAK,2BAA2B;AAEjD,eAAW,CAAC,MAAM,IAAI,KAAK,KAAK,WAAW;AACvC,UAAI,CAAC,KAAK,QAAQ,QAAQ;AACtB,aAAK,QAAQ,KAAK;AAAA,MACtB;AAAA,IACJ;AACA,SAAK,UAAU,MAAM;AAAA,EACzB;AACJ;","names":["proc"]}
+{"version":3,"sources":["../src/spawner.ts"],"sourcesContent":["import type { App, Driver, ProcessConfig } from '@iskra-bun/core';\nimport type { FileSink } from 'bun';\nimport { Subprocess } from 'bun';\n\ninterface RunningProcess {\n    process: Subprocess;\n    config: ProcessConfig;\n    name: string;\n    restarts: number;\n    startedAt: number;\n    /** Current computed backoff delay in ms (grows with each crash) */\n    currentBackoffMs: number;\n}\n\nexport class ProcessManager implements Driver {\n    name = 'ProcessManager';\n    private app: App | null = null;\n    private processes: Map<string, RunningProcess> = new Map();\n    private stopping = false;\n\n    init(app: App) {\n        this.app = app;\n    }\n\n    async start() {\n        if (!this.app) return;\n        const processConfigs = this.app.config.processes;\n\n        if (!processConfigs) {\n            this.app.logger.debug('No processes configured.');\n            return;\n        }\n\n        this.app.logger.info(`Starting ${Object.keys(processConfigs).length} processes...`);\n\n        for (const [name, config] of Object.entries(processConfigs)) {\n            this.spawnProcess(name, config);\n        }\n    }\n\n    /**\n     * Spawn and register a new process at runtime. Reuses the existing internal\n     * spawn logic and respects the process mode (stdio/daemon/oneshot).\n     *\n     * @throws {Error} if a process with the given name is already registered.\n     */\n    async spawn(name: string, config: ProcessConfig): Promise<void> {\n        if (this.processes.has(name)) {\n            throw new Error(`Process '${name}' is already registered. Kill it first or use a different name.`);\n        }\n        this.spawnProcess(name, config);\n    }\n\n    /**\n     * Gracefully stop and remove a single named process. Sends SIGTERM, then\n     * escalates to SIGKILL after `gracefulTimeoutMs`. The worst-case wait before\n     * this method resolves is `gracefulTimeoutMs * 2`: `gracefulTimeoutMs` for the\n     * SIGKILL escalation plus another `gracefulTimeoutMs` grace window for the\n     * process to actually exit afterwards. If the process still has not exited by\n     * then, it is reported as an orphan via `app.logger.error`.\n     *\n     * @throws {Error} if no process with the given name exists.\n     */\n    async kill(name: string, gracefulTimeoutMs = 5000): Promise<void> {\n        const procInfo = this.processes.get(name);\n        if (!procInfo) {\n            throw new Error(`Process '${name}' not found. It may have already exited or never been spawned.`);\n        }\n\n        // Remove from the map before terminating so handleExit won't try to restart it\n        this.processes.delete(name);\n\n        const proc = procInfo.process;\n        if (proc.killed) return;\n\n        await this.terminate(name, proc, gracefulTimeoutMs);\n    }\n\n    /**\n     * Send SIGTERM, escalate to SIGKILL after `gracefulTimeoutMs`, and wait up to\n     * `gracefulTimeoutMs * 2` for the process to exit. After the race settles, if\n     * the process is still alive it is surfaced as an orphan via `app.logger.error`\n     * so a hung shutdown is observable instead of silently succeeding.\n     */\n    private async terminate(name: string, proc: Subprocess, gracefulTimeoutMs: number): Promise<void> {\n        proc.kill('SIGTERM');\n\n        const deadline = gracefulTimeoutMs * 2;\n        const forceKillTimer = setTimeout(() => {\n            if (!proc.killed) {\n                this.app?.logger.warn(`Process ${name} did not exit within ${gracefulTimeoutMs}ms; sending SIGKILL`);\n                proc.kill();\n            }\n        }, gracefulTimeoutMs);\n\n        try {\n            await Promise.race([\n                proc.exited,\n                new Promise<void>(r => setTimeout(r, deadline)),\n            ]);\n        } finally {\n            clearTimeout(forceKillTimer);\n        }\n\n        if (!proc.killed) {\n            this.app?.logger.error(\n                { name },\n                `Process ${name} survived SIGTERM and SIGKILL and is now an orphan; manual cleanup may be required`,\n            );\n        }\n    }\n\n    private async readStdOut(name: string, stream: ReadableStream) {\n        const reader = stream.getReader();\n        const decoder = new TextDecoder();\n        let buffer = '';\n\n        try {\n            while (true) {\n                const { done, value } = await reader.read();\n                if (done) break;\n\n                buffer += decoder.decode(value, { stream: true });\n\n                const lines = buffer.split('\\n');\n                // Keep the last chunk if it's not a complete line (doesn't end with \\n)\n                buffer = lines.pop() || '';\n\n                for (const line of lines) {\n                    if (!line.trim()) continue;\n                    this.processLine(name, line);\n                }\n            }\n        } catch (err) {\n            // A thrown error here is a broken pipe mid-read, distinct from the\n            // normal end-of-stream (`done: true`) that exits the loop above.\n            this.app?.logger.debug({ err, name }, `stdout reader for process ${name} failed`);\n        }\n    }\n\n    private processLine(name: string, line: string) {\n        try {\n            // Try to parse as JSON Event\n            const json = JSON.parse(line);\n            this.app?.emit('process:message', { name, message: json });\n        } catch {\n            // Fallback to raw log\n            this.app?.emit('process:log', { name, text: line });\n        }\n    }\n\n    /**\n     * Compute the next backoff delay for a process restart.\n     *\n     * - If no `restartBackoff` config is provided, returns the flat 1000 ms default.\n     * - The FIRST restart (`restarts === 0`) waits exactly `currentBackoffMs`\n     *   (seeded to `initialMs` on spawn); exponential growth begins on the SECOND\n     *   restart with `min(currentMs * factor, maxMs)`.\n     * - If the process was stable (uptime > restartCooldown), the backoff resets to initialMs.\n     */\n    private computeBackoffMs(procInfo: RunningProcess): number {\n        const backoffCfg = procInfo.config.restartBackoff;\n        if (!backoffCfg) {\n            return 1000;\n        }\n\n        const cooldown = procInfo.config.restartCooldown ?? 60000;\n        const uptime = Date.now() - procInfo.startedAt;\n        if (uptime > cooldown) {\n            // Process was stable — reset to initial delay\n            return backoffCfg.initialMs ?? 1000;\n        }\n\n        const maxMs = backoffCfg.maxMs ?? 30000;\n        const initialMs = backoffCfg.initialMs ?? 1000;\n\n        // The very first restart (no prior restarts and the backoff has not yet\n        // grown past its initial value) waits exactly initialMs — exponential\n        // growth begins on the SECOND restart.\n        if (procInfo.restarts === 0 && procInfo.currentBackoffMs === initialMs) {\n            return Math.min(procInfo.currentBackoffMs, maxMs);\n        }\n\n        const factor = backoffCfg.factor ?? 2;\n        const next = Math.min(procInfo.currentBackoffMs * factor, maxMs);\n        return next;\n    }\n\n    private handleExit(name: string, exitCode: number) {\n        if (this.stopping) return;\n\n        const procInfo = this.processes.get(name);\n        if (!procInfo) return;\n\n        this.app?.logger.warn(`Process ${name} exited with code ${exitCode}`);\n\n        // Remove from map so we don't try to kill it again on stop()\n        this.processes.delete(name);\n\n        // oneshot processes run to completion once and are never restarted\n        if (procInfo.config.mode === 'oneshot') {\n            this.app?.emit('process:exit', { name, exitCode });\n            return;\n        }\n\n        if (procInfo.config.restartOnCrash) {\n            const maxRestarts = procInfo.config.maxRestarts ?? 10;\n            const cooldown = procInfo.config.restartCooldown ?? 60000;\n            const uptime = Date.now() - procInfo.startedAt;\n\n            // If the process ran longer than the cooldown, consider it stable and reset the counter\n            const restarts = uptime > cooldown ? 1 : procInfo.restarts + 1;\n\n            if (restarts > maxRestarts) {\n                this.app?.logger.error(`Process ${name} exceeded max restarts (${maxRestarts}). Not restarting.`);\n                this.app?.emit('process:max-restarts', { name, restarts: procInfo.restarts, maxRestarts });\n                return;\n            }\n\n            const delayMs = this.computeBackoffMs(procInfo);\n\n            this.app?.logger.info(`Restarting process: ${name} (Attempt ${restarts}/${maxRestarts}) in ${delayMs}ms`);\n\n            setTimeout(() => {\n                this.spawnProcess(name, procInfo.config, restarts, delayMs);\n            }, delayMs);\n        }\n    }\n\n    // Updated spawn signature to track restarts and backoff state\n    private spawnProcess(name: string, config: ProcessConfig, restarts = 0, currentBackoffMs?: number) {\n        if (this.stopping || !this.app) return;\n\n        const initialBackoffMs = config.restartBackoff?.initialMs ?? 1000;\n\n        this.app.logger.info(`Spawning process: ${name} (${config.command} ${config.args?.join(' ') || ''})`);\n\n        try {\n            const proc = Bun.spawn(\n                [config.command, ...(config.args || [])],\n                {\n                    env: { ...process.env, ...config.env },\n                    stdout: config.mode === 'stdio' ? 'pipe' : 'inherit',\n                    stderr: config.mode === 'stdio' ? 'pipe' : 'inherit',\n                    stdin: config.mode === 'stdio' ? 'pipe' : 'ignore',\n                    onExit: (_proc, exitCode, _signalCode, _error) => {\n                        this.handleExit(name, exitCode || 0);\n                    }\n                }\n            );\n\n            this.processes.set(name, {\n                process: proc,\n                config,\n                name,\n                restarts,\n                startedAt: Date.now(),\n                currentBackoffMs: currentBackoffMs ?? initialBackoffMs,\n            });\n\n            if (config.mode === 'stdio') {\n                if (proc.stdout) this.readStdOut(name, proc.stdout);\n                if (proc.stderr) this.readStdErr(name, proc.stderr);\n            }\n\n        } catch (err) {\n            this.app.logger.error({ err }, `Failed to spawn process: ${name}`);\n        }\n    }\n\n    private async readStdErr(name: string, stream: ReadableStream) {\n        const reader = stream.getReader();\n        const decoder = new TextDecoder();\n\n        try {\n            while (true) {\n                const { done, value } = await reader.read();\n                if (done) break;\n                const text = decoder.decode(value, { stream: true });\n                if (text.trim()) {\n                    this.app?.emit('process:error', { name, text });\n                }\n            }\n        } catch (err) {\n            // A thrown error here is a broken pipe mid-read, distinct from the\n            // normal end-of-stream (`done: true`) that exits the loop above.\n            this.app?.logger.debug({ err, name }, `stderr reader for process ${name} failed`);\n        }\n    }\n\n    // Send data to process stdin\n    async send(name: string, data: any) {\n        const procInfo = this.processes.get(name);\n        if (!procInfo) {\n            this.app?.logger.warn(`Cannot send message to non-existent process: ${name}`);\n            return;\n        }\n\n        if (procInfo.config.mode !== 'stdio' || !procInfo.process.stdin) {\n            this.app?.logger.warn(`Cannot send message to process ${name} (mode is not stdio or stdin is closed)`);\n            return;\n        }\n\n        // Bun's Subprocess.stdin is a FileSink when stdin is piped.\n        const stdin = procInfo.process.stdin as FileSink;\n\n        try {\n            // If data is object, stringify it and add newline\n            const message = typeof data === 'string' ? data : JSON.stringify(data);\n            stdin.write(message + '\\n');\n            // flush is optional on the FileSink surface — call it only if present.\n            if (typeof stdin.flush === 'function') {\n                stdin.flush();\n            }\n        } catch (err) {\n            this.app?.logger.error({ err }, `Failed to write to process ${name}`);\n        }\n    }\n\n    async stop(gracefulTimeoutMs = 5000) {\n        this.stopping = true;\n        this.app?.logger.info('Stopping all processes...');\n\n        const entries = [...this.processes.entries()];\n        this.processes.clear();\n\n        await Promise.all(\n            entries.map(async ([name, info]) => {\n                const proc = info.process;\n                if (proc.killed) return;\n                await this.terminate(name, proc, gracefulTimeoutMs);\n            })\n        );\n    }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@iskra-bun/process-kit",
-    "version": "0.1.0",
+    "version": "0.2.0",
     "description": "Gestion de procesos externos (Python, binarios) para Iskra.",
     "keywords": [
         "iskra",
@@ -46,7 +46,7 @@
         "build": "tsup --config ../../tsup.config.ts"
     },
     "dependencies": {
-        "@iskra-bun/core": "0.1.0",
+        "@iskra-bun/core": "0.1.1",
         "zod": "^3.24.1"
     },
     "devDependencies": {

package/src/spawner.ts

@@ -1,4 +1,5 @@
 import type { App, Driver, ProcessConfig } from '@iskra-bun/core';
+import type { FileSink } from 'bun';
 import { Subprocess } from 'bun';
 
 interface RunningProcess {
@@ -7,6 +8,8 @@ interface RunningProcess {
     name: string;
     restarts: number;
     startedAt: number;
+    /** Current computed backoff delay in ms (grows with each crash) */
+    currentBackoffMs: number;
 }
 
 export class ProcessManager implements Driver {
@@ -35,6 +38,78 @@ export class ProcessManager implements Driver {
         }
     }
 
+    /**
+     * Spawn and register a new process at runtime. Reuses the existing internal
+     * spawn logic and respects the process mode (stdio/daemon/oneshot).
+     *
+     * @throws {Error} if a process with the given name is already registered.
+     */
+    async spawn(name: string, config: ProcessConfig): Promise<void> {
+        if (this.processes.has(name)) {
+            throw new Error(`Process '${name}' is already registered. Kill it first or use a different name.`);
+        }
+        this.spawnProcess(name, config);
+    }
+
+    /**
+     * Gracefully stop and remove a single named process. Sends SIGTERM, then
+     * escalates to SIGKILL after `gracefulTimeoutMs`. The worst-case wait before
+     * this method resolves is `gracefulTimeoutMs * 2`: `gracefulTimeoutMs` for the
+     * SIGKILL escalation plus another `gracefulTimeoutMs` grace window for the
+     * process to actually exit afterwards. If the process still has not exited by
+     * then, it is reported as an orphan via `app.logger.error`.
+     *
+     * @throws {Error} if no process with the given name exists.
+     */
+    async kill(name: string, gracefulTimeoutMs = 5000): Promise<void> {
+        const procInfo = this.processes.get(name);
+        if (!procInfo) {
+            throw new Error(`Process '${name}' not found. It may have already exited or never been spawned.`);
+        }
+
+        // Remove from the map before terminating so handleExit won't try to restart it
+        this.processes.delete(name);
+
+        const proc = procInfo.process;
+        if (proc.killed) return;
+
+        await this.terminate(name, proc, gracefulTimeoutMs);
+    }
+
+    /**
+     * Send SIGTERM, escalate to SIGKILL after `gracefulTimeoutMs`, and wait up to
+     * `gracefulTimeoutMs * 2` for the process to exit. After the race settles, if
+     * the process is still alive it is surfaced as an orphan via `app.logger.error`
+     * so a hung shutdown is observable instead of silently succeeding.
+     */
+    private async terminate(name: string, proc: Subprocess, gracefulTimeoutMs: number): Promise<void> {
+        proc.kill('SIGTERM');
+
+        const deadline = gracefulTimeoutMs * 2;
+        const forceKillTimer = setTimeout(() => {
+            if (!proc.killed) {
+                this.app?.logger.warn(`Process ${name} did not exit within ${gracefulTimeoutMs}ms; sending SIGKILL`);
+                proc.kill();
+            }
+        }, gracefulTimeoutMs);
+
+        try {
+            await Promise.race([
+                proc.exited,
+                new Promise<void>(r => setTimeout(r, deadline)),
+            ]);
+        } finally {
+            clearTimeout(forceKillTimer);
+        }
+
+        if (!proc.killed) {
+            this.app?.logger.error(
+                { name },
+                `Process ${name} survived SIGTERM and SIGKILL and is now an orphan; manual cleanup may be required`,
+            );
+        }
+    }
+
     private async readStdOut(name: string, stream: ReadableStream) {
         const reader = stream.getReader();
         const decoder = new TextDecoder();
@@ -57,7 +132,9 @@ export class ProcessManager implements Driver {
                 }
             }
         } catch (err) {
-            // Stream closed or error
+            // A thrown error here is a broken pipe mid-read, distinct from the
+            // normal end-of-stream (`done: true`) that exits the loop above.
+            this.app?.logger.debug({ err, name }, `stdout reader for process ${name} failed`);
         }
     }
 
@@ -72,7 +149,44 @@ export class ProcessManager implements Driver {
         }
     }
 
-    private handleExit(name: string, exitCode: number, signalCode: number) {
+    /**
+     * Compute the next backoff delay for a process restart.
+     *
+     * - If no `restartBackoff` config is provided, returns the flat 1000 ms default.
+     * - The FIRST restart (`restarts === 0`) waits exactly `currentBackoffMs`
+     *   (seeded to `initialMs` on spawn); exponential growth begins on the SECOND
+     *   restart with `min(currentMs * factor, maxMs)`.
+     * - If the process was stable (uptime > restartCooldown), the backoff resets to initialMs.
+     */
+    private computeBackoffMs(procInfo: RunningProcess): number {
+        const backoffCfg = procInfo.config.restartBackoff;
+        if (!backoffCfg) {
+            return 1000;
+        }
+
+        const cooldown = procInfo.config.restartCooldown ?? 60000;
+        const uptime = Date.now() - procInfo.startedAt;
+        if (uptime > cooldown) {
+            // Process was stable — reset to initial delay
+            return backoffCfg.initialMs ?? 1000;
+        }
+
+        const maxMs = backoffCfg.maxMs ?? 30000;
+        const initialMs = backoffCfg.initialMs ?? 1000;
+
+        // The very first restart (no prior restarts and the backoff has not yet
+        // grown past its initial value) waits exactly initialMs — exponential
+        // growth begins on the SECOND restart.
+        if (procInfo.restarts === 0 && procInfo.currentBackoffMs === initialMs) {
+            return Math.min(procInfo.currentBackoffMs, maxMs);
+        }
+
+        const factor = backoffCfg.factor ?? 2;
+        const next = Math.min(procInfo.currentBackoffMs * factor, maxMs);
+        return next;
+    }
+
+    private handleExit(name: string, exitCode: number) {
         if (this.stopping) return;
 
         const procInfo = this.processes.get(name);
@@ -83,6 +197,12 @@ export class ProcessManager implements Driver {
         // Remove from map so we don't try to kill it again on stop()
         this.processes.delete(name);
 
+        // oneshot processes run to completion once and are never restarted
+        if (procInfo.config.mode === 'oneshot') {
+            this.app?.emit('process:exit', { name, exitCode });
+            return;
+        }
+
         if (procInfo.config.restartOnCrash) {
             const maxRestarts = procInfo.config.maxRestarts ?? 10;
             const cooldown = procInfo.config.restartCooldown ?? 60000;
@@ -97,18 +217,22 @@ export class ProcessManager implements Driver {
                 return;
             }
 
-            this.app?.logger.info(`Restarting process: ${name} (Attempt ${restarts}/${maxRestarts})`);
+            const delayMs = this.computeBackoffMs(procInfo);
+
+            this.app?.logger.info(`Restarting process: ${name} (Attempt ${restarts}/${maxRestarts}) in ${delayMs}ms`);
 
             setTimeout(() => {
-                this.spawnProcess(name, procInfo.config, restarts);
-            }, 1000);
+                this.spawnProcess(name, procInfo.config, restarts, delayMs);
+            }, delayMs);
         }
     }
 
-    // Updated spawn signature to track restarts
-    private spawnProcess(name: string, config: ProcessConfig, restarts = 0) {
+    // Updated spawn signature to track restarts and backoff state
+    private spawnProcess(name: string, config: ProcessConfig, restarts = 0, currentBackoffMs?: number) {
         if (this.stopping || !this.app) return;
 
+        const initialBackoffMs = config.restartBackoff?.initialMs ?? 1000;
+
         this.app.logger.info(`Spawning process: ${name} (${config.command} ${config.args?.join(' ') || ''})`);
 
         try {
@@ -119,8 +243,8 @@ export class ProcessManager implements Driver {
                     stdout: config.mode === 'stdio' ? 'pipe' : 'inherit',
                     stderr: config.mode === 'stdio' ? 'pipe' : 'inherit',
                     stdin: config.mode === 'stdio' ? 'pipe' : 'ignore',
-                    onExit: (proc, exitCode, signalCode, error) => {
-                        this.handleExit(name, exitCode || 0, signalCode || 0);
+                    onExit: (_proc, exitCode, _signalCode, _error) => {
+                        this.handleExit(name, exitCode || 0);
                     }
                 }
             );
@@ -131,6 +255,7 @@ export class ProcessManager implements Driver {
                 name,
                 restarts,
                 startedAt: Date.now(),
+                currentBackoffMs: currentBackoffMs ?? initialBackoffMs,
             });
 
             if (config.mode === 'stdio') {
@@ -157,7 +282,9 @@ export class ProcessManager implements Driver {
                 }
             }
         } catch (err) {
-            // Stream closed
+            // A thrown error here is a broken pipe mid-read, distinct from the
+            // normal end-of-stream (`done: true`) that exits the loop above.
+            this.app?.logger.debug({ err, name }, `stderr reader for process ${name} failed`);
         }
     }
 
@@ -174,28 +301,35 @@ export class ProcessManager implements Driver {
             return;
         }
 
-        // Bun's Subprocess.stdin is a FileSink
-        const stdin = procInfo.process.stdin as any;
+        // Bun's Subprocess.stdin is a FileSink when stdin is piped.
+        const stdin = procInfo.process.stdin as FileSink;
 
         try {
             // If data is object, stringify it and add newline
             const message = typeof data === 'string' ? data : JSON.stringify(data);
             stdin.write(message + '\n');
-            stdin.flush();
+            // flush is optional on the FileSink surface — call it only if present.
+            if (typeof stdin.flush === 'function') {
+                stdin.flush();
+            }
         } catch (err) {
             this.app?.logger.error({ err }, `Failed to write to process ${name}`);
         }
     }
 
-    async stop() {
+    async stop(gracefulTimeoutMs = 5000) {
         this.stopping = true;
         this.app?.logger.info('Stopping all processes...');
 
-        for (const [name, info] of this.processes) {
-            if (!info.process.killed) {
-                info.process.kill();
-            }
-        }
+        const entries = [...this.processes.entries()];
         this.processes.clear();
+
+        await Promise.all(
+            entries.map(async ([name, info]) => {
+                const proc = info.process;
+                if (proc.killed) return;
+                await this.terminate(name, proc, gracefulTimeoutMs);
+            })
+        );
     }
 }