feat(01-03): create process manager with spawn/stop
- ProcessManager class with execa for child process spawning - spawn() starts detached background processes - stop() graceful shutdown with SIGTERM then SIGKILL after 5s timeout - stopAll() terminates all managed processes - restart() stops and respawns with same config - isRunning() probes actual process state - Proper promise handling for killed processes
This commit is contained in:
Lukas May
9
src/process/index.ts
Normal file
9
src/process/index.ts
Normal file
@@ -0,0 +1,9 @@
|
||||
/**
|
||||
* Process Module
|
||||
*
|
||||
* Exports for process management functionality.
|
||||
*/
|
||||
|
||||
export { ProcessManager } from './manager.js';
|
||||
export { ProcessRegistry } from './registry.js';
|
||||
export type { ProcessInfo, ProcessStatus, SpawnOptions } from './types.js';
|
||||
268
src/process/manager.ts
Normal file
268
src/process/manager.ts
Normal file
@@ -0,0 +1,268 @@
|
||||
/**
|
||||
* Process Manager
|
||||
*
|
||||
* Manages spawning, stopping, and lifecycle of child processes.
|
||||
* Uses execa for process spawning with detached mode support.
|
||||
*/
|
||||
|
||||
import { execa, type ResultPromise } from 'execa';
|
||||
import type { ProcessInfo, SpawnOptions } from './types.js';
|
||||
import type { ProcessRegistry } from './registry.js';
|
||||
|
||||
/** Stop timeout in milliseconds before sending SIGKILL */
|
||||
const STOP_TIMEOUT_MS = 5000;
|
||||
|
||||
/**
|
||||
* Internal tracking for spawned process handles.
|
||||
* Maps process ID to execa subprocess for control operations.
|
||||
*/
|
||||
interface ProcessHandle {
|
||||
subprocess: ResultPromise;
|
||||
options: SpawnOptions;
|
||||
}
|
||||
|
||||
/**
|
||||
* Manager for spawning, tracking, and controlling child processes.
|
||||
*/
|
||||
export class ProcessManager {
|
||||
private handles: Map<string, ProcessHandle> = new Map();
|
||||
|
||||
/**
|
||||
* Create a new ProcessManager.
|
||||
* @param registry - Registry for tracking process metadata
|
||||
*/
|
||||
constructor(private registry: ProcessRegistry) {}
|
||||
|
||||
/**
|
||||
* Spawn a new child process.
|
||||
* @param options - Spawn configuration
|
||||
* @returns Process info for the spawned process
|
||||
* @throws If process fails to start
|
||||
*/
|
||||
async spawn(options: SpawnOptions): Promise<ProcessInfo> {
|
||||
const { id, command, args = [], cwd, env } = options;
|
||||
|
||||
// Check if process with this ID already exists
|
||||
const existing = this.registry.get(id);
|
||||
if (existing && existing.status === 'running') {
|
||||
throw new Error(`Process with id '${id}' is already running`);
|
||||
}
|
||||
|
||||
// Spawn the process in detached mode
|
||||
const subprocess = execa(command, args, {
|
||||
cwd,
|
||||
env: env ? { ...process.env, ...env } : undefined,
|
||||
detached: true,
|
||||
stdio: 'ignore', // Don't inherit stdio for background processes
|
||||
});
|
||||
|
||||
// Ensure we have a PID
|
||||
const pid = subprocess.pid;
|
||||
if (pid === undefined) {
|
||||
throw new Error(`Failed to get PID for process '${id}'`);
|
||||
}
|
||||
|
||||
// Create process info
|
||||
const info: ProcessInfo = {
|
||||
id,
|
||||
pid,
|
||||
command,
|
||||
args,
|
||||
startedAt: new Date(),
|
||||
status: 'running',
|
||||
};
|
||||
|
||||
// Store handle for later control
|
||||
this.handles.set(id, { subprocess, options });
|
||||
|
||||
// Register in registry
|
||||
this.registry.register(info);
|
||||
|
||||
// Set up exit handler to update status
|
||||
subprocess.on('exit', (code, signal) => {
|
||||
const status = code === 0 ? 'stopped' : 'crashed';
|
||||
this.registry.updateStatus(id, status);
|
||||
this.handles.delete(id);
|
||||
});
|
||||
|
||||
// Suppress unhandled rejection when process is killed
|
||||
// This is expected behavior - we're intentionally killing processes
|
||||
subprocess.catch(() => {
|
||||
// Intentionally ignored - we handle exit via the 'exit' event
|
||||
});
|
||||
|
||||
// Unref the subprocess so it doesn't keep the parent alive
|
||||
subprocess.unref();
|
||||
|
||||
return info;
|
||||
}
|
||||
|
||||
/**
|
||||
* Stop a running process.
|
||||
* Sends SIGTERM first, then SIGKILL after timeout if needed.
|
||||
* @param id - Process ID to stop
|
||||
* @throws If process not found
|
||||
*/
|
||||
async stop(id: string): Promise<void> {
|
||||
const handle = this.handles.get(id);
|
||||
const info = this.registry.get(id);
|
||||
|
||||
if (!info) {
|
||||
throw new Error(`Process with id '${id}' not found`);
|
||||
}
|
||||
|
||||
if (info.status !== 'running') {
|
||||
// Already stopped, just clean up
|
||||
this.handles.delete(id);
|
||||
return;
|
||||
}
|
||||
|
||||
if (!handle) {
|
||||
// Process exists in registry but we don't have a handle
|
||||
// Try to kill by PID directly
|
||||
try {
|
||||
process.kill(info.pid, 'SIGTERM');
|
||||
await this.waitForExit(info.pid, STOP_TIMEOUT_MS);
|
||||
} catch {
|
||||
// Process might already be dead
|
||||
}
|
||||
this.registry.updateStatus(id, 'stopped');
|
||||
return;
|
||||
}
|
||||
|
||||
// Send SIGTERM
|
||||
handle.subprocess.kill('SIGTERM');
|
||||
|
||||
// Wait for graceful shutdown
|
||||
const exited = await this.waitForProcessExit(handle.subprocess, STOP_TIMEOUT_MS);
|
||||
|
||||
if (!exited) {
|
||||
// Force kill with SIGKILL
|
||||
handle.subprocess.kill('SIGKILL');
|
||||
await this.waitForProcessExit(handle.subprocess, 1000).catch(() => {});
|
||||
}
|
||||
|
||||
// Update status (exit handler should have done this, but ensure it)
|
||||
this.registry.updateStatus(id, 'stopped');
|
||||
this.handles.delete(id);
|
||||
}
|
||||
|
||||
/**
|
||||
* Stop all running processes.
|
||||
*/
|
||||
async stopAll(): Promise<void> {
|
||||
const processes = this.registry.getAll().filter(p => p.status === 'running');
|
||||
await Promise.all(processes.map(p => this.stop(p.id).catch(() => {})));
|
||||
}
|
||||
|
||||
/**
|
||||
* Restart a process with the same configuration.
|
||||
* @param id - Process ID to restart
|
||||
* @returns New process info
|
||||
* @throws If process not found or original config unavailable
|
||||
*/
|
||||
async restart(id: string): Promise<ProcessInfo> {
|
||||
const handle = this.handles.get(id);
|
||||
const info = this.registry.get(id);
|
||||
|
||||
if (!info) {
|
||||
throw new Error(`Process with id '${id}' not found`);
|
||||
}
|
||||
|
||||
// Get original spawn options
|
||||
let options: SpawnOptions;
|
||||
if (handle) {
|
||||
options = handle.options;
|
||||
} else {
|
||||
// Reconstruct options from process info
|
||||
options = {
|
||||
id,
|
||||
command: info.command,
|
||||
args: info.args,
|
||||
};
|
||||
}
|
||||
|
||||
// Stop if running
|
||||
if (info.status === 'running') {
|
||||
await this.stop(id);
|
||||
}
|
||||
|
||||
// Unregister old process
|
||||
this.registry.unregister(id);
|
||||
|
||||
// Spawn with same options
|
||||
return this.spawn(options);
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if a process is currently running.
|
||||
* @param id - Process ID to check
|
||||
* @returns true if process exists and is running
|
||||
*/
|
||||
isRunning(id: string): boolean {
|
||||
const info = this.registry.get(id);
|
||||
if (!info || info.status !== 'running') {
|
||||
return false;
|
||||
}
|
||||
|
||||
// Double-check by probing the actual process
|
||||
try {
|
||||
process.kill(info.pid, 0);
|
||||
return true;
|
||||
} catch {
|
||||
// Process is dead, update registry
|
||||
this.registry.updateStatus(id, 'crashed');
|
||||
this.handles.delete(id);
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Wait for a subprocess to exit within a timeout.
|
||||
* @returns true if process exited, false if timeout
|
||||
*/
|
||||
private waitForProcessExit(subprocess: ResultPromise, timeoutMs: number): Promise<boolean> {
|
||||
return new Promise(resolve => {
|
||||
const timeout = setTimeout(() => {
|
||||
resolve(false);
|
||||
}, timeoutMs);
|
||||
|
||||
// Use both then and catch to handle success and kill scenarios
|
||||
subprocess
|
||||
.then(() => {
|
||||
clearTimeout(timeout);
|
||||
resolve(true);
|
||||
})
|
||||
.catch(() => {
|
||||
// Process was killed (expected) - this is success for our purposes
|
||||
clearTimeout(timeout);
|
||||
resolve(true);
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Wait for a PID to exit within a timeout.
|
||||
* @returns true if process exited, false if timeout
|
||||
*/
|
||||
private waitForExit(pid: number, timeoutMs: number): Promise<boolean> {
|
||||
return new Promise(resolve => {
|
||||
const start = Date.now();
|
||||
const check = () => {
|
||||
try {
|
||||
process.kill(pid, 0);
|
||||
// Still alive
|
||||
if (Date.now() - start >= timeoutMs) {
|
||||
resolve(false);
|
||||
} else {
|
||||
setTimeout(check, 100);
|
||||
}
|
||||
} catch {
|
||||
// Dead
|
||||
resolve(true);
|
||||
}
|
||||
};
|
||||
check();
|
||||
});
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user