feat: add elegant ending process library

Author: zhufuyi

pkg/process/README.md

@@ -0,0 +1,64 @@
+## Go Process Kill Utility
+
+A simple, cross-platform Go package for terminating processes by their PID. It prioritizes a graceful shutdown before resorting to a force kill, ensuring that applications have a chance to clean up resources.
+
+### Features
+
+-   **Cross-Platform:** Works seamlessly on Windows, Linux, and macOS.
+-   **Graceful Shutdown First:** Always attempts to terminate a process gracefully before forcing it to exit.
+-   **Automatic Fallback:** If a graceful shutdown fails or the process does not exit within a timeout period (5 seconds), it automatically performs a force kill.
+-   **Simple API:** A single `Kill(pid)` function makes it incredibly easy to use.
+
+<br>
+
+### Usage
+
+Here is a simple example of how to start a process and then terminate it using this package.
+
+```go
+package main
+
+import (
+	"fmt"
+	"log"
+	"os/exec"
+	"runtime"
+	"time"
+
+	"github.com/go-dev-frame/sponge/pkg/process"
+)
+
+func main() {
+	var cmd *exec.Cmd
+
+	// Start a long-running process appropriate for the OS.
+	if runtime.GOOS == "windows" {
+		cmd = exec.Command("timeout", "/t", "30")
+	} else {
+		cmd = exec.Command("sleep", "30")
+	}
+
+	err := cmd.Start()
+	if err != nil {
+		log.Fatalf("Failed to start command: %v", err)
+	}
+
+	pid := cmd.Process.Pid
+	fmt.Printf("Started process with PID: %d\n", pid)
+
+	// Give the process a moment to initialize.
+	time.Sleep(1 * time.Second)
+	fmt.Printf("Attempting to kill process %d...\n", pid)
+
+	// Use the Kill function to terminate it.
+	if err = process.Kill(pid); err != nil {
+		log.Fatalf("Failed to kill process: %v", err)
+	}
+
+	fmt.Printf("Successfully terminated process %d.\n", pid)
+
+	// The cmd.Wait() call will now return an error because the process was killed.
+	err = cmd.Wait()
+	fmt.Printf("Process wait result: %v\n", err)
+}
+```

pkg/process/kill.go

@@ -0,0 +1,44 @@
+// Package process provides functions to manage processes.
+package process
+
+import (
+	"fmt"
+	"time"
+)
+
+// Kill terminates a process by its PID.
+func Kill(pid int) error {
+	if pid < 1 {
+		return fmt.Errorf("invalid PID: %d", pid)
+	}
+
+	// 1. First, attempt a graceful shutdown.
+	ok := tryGracefulExit(pid)
+	if ok {
+		// Wait for confirmation of exit: check every 0.25s for up to 10 times (5s total).
+		waitInterval := 250 * time.Millisecond
+		maxAttempts := 20
+		for i := 0; i < maxAttempts; i++ {
+			time.Sleep(waitInterval)
+			if !isProcessRunning(pid) {
+				return nil
+			}
+		}
+	} else {
+		// If the graceful signal failed, check if the process is already gone.
+		if !isProcessRunning(pid) {
+			return nil
+		}
+	}
+
+	// 2. If graceful shutdown failed or timed out, force kill the process.
+	ok = forceKill(pid)
+	if !ok {
+		// If force kill failed, do one last check to see if it's running.
+		if !isProcessRunning(pid) {
+			return nil
+		}
+		return fmt.Errorf("failed to terminate PID=%d (permissions or process does not exist)", pid)
+	}
+	return nil
+}

pkg/process/kill_test.go

@@ -0,0 +1,132 @@
+package process
+
+import (
+	"os/exec"
+	"runtime"
+	"testing"
+	"time"
+)
+
+func startTestProcess(t *testing.T) *exec.Cmd {
+	t.Helper()
+	var cmd *exec.Cmd
+	if runtime.GOOS == "windows" {
+		cmd = getTestProcessCmd("timeout", "/t", "30")
+	} else {
+		cmd = getTestProcessCmd("sleep", "30")
+	}
+	err := cmd.Start()
+	if err != nil {
+		t.Fatalf("Failed to start test process: %v", err)
+	}
+	return cmd
+}
+
+func TestKill_InvalidPID(t *testing.T) {
+	err := Kill(0)
+	if err == nil {
+		t.Error("Expected an error for invalid PID 0, but got nil")
+	}
+}
+
+func TestKill_GracefulExitSuccess(t *testing.T) {
+	cmd := startTestProcess(t)
+	pid := cmd.Process.Pid
+
+	// Ensure the process is running before trying to kill it.
+	if !isProcessRunning(pid) {
+		t.Fatalf("Test process with PID %d should be running but it's not", pid)
+	}
+
+	err := Kill(pid)
+	if err != nil {
+		t.Errorf("Kill should have succeeded gracefully, but got error: %v", err)
+	}
+
+	// Give it a moment to die, then check.
+	time.Sleep(1 * time.Second)
+
+	if isProcessRunning(pid) {
+		if ok := forceKill(pid); !ok {
+			t.Errorf("Process %d should have been terminated gracefully, but it is still running.", pid)
+		}
+	}
+}
+
+func TestKill_ForceKillAfterGracefulTimeout(t *testing.T) {
+	cmd := startTestProcess(t)
+	pid := cmd.Process.Pid
+
+	// To test the timeout path, we'll let Kill do its thing.
+	// The 5-second wait in Kill should expire, triggering forceKill.
+	err := Kill(pid)
+	if err != nil {
+		t.Errorf("Kill should have eventually succeeded with force kill, but got error: %v", err)
+	}
+
+	// We wait slightly longer than the internal timeout of Kill()
+	time.Sleep(6 * time.Second)
+
+	if isProcessRunning(pid) {
+		if err = cmd.Process.Kill(); err != nil {
+			t.Errorf("Process %d should have been force-killed, but it is still running.", pid)
+		}
+	}
+}
+
+func TestKill_NonExistentProcess(t *testing.T) {
+	pid := 999999
+	for isProcessRunning(pid) {
+		pid++
+	}
+
+	err := Kill(pid)
+	if err != nil {
+		t.Errorf("Killing a non-existent process should not return an error, but got: %v", err)
+	}
+}
+
+func TestKill_ForceKillFailure(t *testing.T) {
+	// This scenario is hard to test reliably without special permissions.
+	// For example, trying to kill a critical system process (PID 1 on Linux).
+	// Such a test would be flaky and dangerous.
+	// Instead, we will test the code path where forceKill *reports* failure,
+	// but the process is actually already gone.
+
+	// We can't easily mock `forceKill` to return false, so we'll test the
+	// logic by killing a process and then immediately trying to kill it again.
+	// The second kill attempt might fail on the `forceKill` call, but since
+	// `isProcessRunning` will be false, `Kill` should return nil.
+	cmd := startTestProcess(t)
+	pid := cmd.Process.Pid
+
+	// Kill it once for real
+	forceKill(pid)
+	time.Sleep(100 * time.Millisecond) // Let it die
+
+	if isProcessRunning(pid) {
+		t.Skip("Could not kill process for the first time, skipping test.")
+	}
+
+	// Now call the main Kill function on the already-dead process.
+	// Internally, it might try graceful, then force, which might fail,
+	// but the final check should show the process is not running.
+	err := Kill(pid)
+	if err != nil {
+		t.Errorf("Expected nil error when Kill fails to force-kill an already-dead process, but got: %v", err)
+	}
+}
+
+func TestIsProcessRunning_False(t *testing.T) {
+	pid := 999999
+	for isProcessRunning(pid) { // ensure PID is not running
+		pid++
+	}
+	if isProcessRunning(pid) {
+		t.Errorf("isProcessRunning for non-existent PID %d should be false", pid)
+	}
+}
+
+func getTestProcessCmd(name string, arg ...string) *exec.Cmd {
+	return exec.Command(name, arg...)
+}

pkg/process/kill_unix.go

@@ -0,0 +1,40 @@
+//go:build linux || darwin || freebsd || openbsd || netbsd
+// +build linux darwin freebsd openbsd netbsd
+
+package process
+
+import (
+	"syscall"
+)
+
+// tryGracefulExit: sends SIGTERM, returns true if the signal was sent successfully (does not guarantee immediate exit).
+// On Unix, sending SIGTERM is the conventional way to request a graceful shutdown.
+func tryGracefulExit(pid int) bool {
+	// A nil error from syscall.Kill indicates the signal was sent successfully
+	// (i.e., the target process exists and received the signal).
+	err := syscall.Kill(pid, syscall.SIGTERM)
+	return err == nil
+}
+
+// forceKill: sends SIGKILL to forcibly terminate the process.
+func forceKill(pid int) bool {
+	err := syscall.Kill(pid, syscall.SIGKILL)
+	return err == nil
+}
+
+// isProcessRunning: checks if a process exists using syscall.Kill(pid, 0).
+func isProcessRunning(pid int) bool {
+	err := syscall.Kill(pid, 0)
+	// err == nil => process exists
+	// err == ESRCH => process does not exist
+	// err == EPERM => process exists, but we don't have permission to send a signal (we count this as running)
+	if err == nil {
+		return true
+	}
+	// If the error is "operation not permitted," it means the process exists, but we lack permissions.
+	if err == syscall.EPERM {
+		return true
+	}
+	// Other errors (like ESRCH) indicate the process does not exist or another issue occurred.
+	return false
+}

pkg/process/kill_unix_test.go

@@ -0,0 +1,81 @@
+//go:build linux || darwin || freebsd || openbsd || netbsd
+// +build linux darwin freebsd openbsd netbsd
+
+package process
+
+import (
+	"os/exec"
+	"testing"
+	"time"
+)
+
+// Platform-specific implementation for starting a test process.
+//func getTestProcessCmd(name string, arg ...string) *exec.Cmd {
+//	cmd := exec.Command(name, arg...)
+//	// Set a process group ID, so we can kill the whole group if needed,
+//	// and to prevent signals from affecting the test runner.
+//	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+//	return cmd
+//}
+
+func TestUnix_IsProcessRunning_True(t *testing.T) {
+	cmd := exec.Command("sleep", "10")
+	err := cmd.Start()
+	if err != nil {
+		t.Fatalf("Failed to start process: %v", err)
+	}
+	defer cmd.Process.Kill()
+
+	pid := cmd.Process.Pid
+	if !isProcessRunning(pid) {
+		t.Errorf("isProcessRunning for PID %d should be true", pid)
+	}
+}
+
+func TestUnix_TryGracefulExit(t *testing.T) {
+	cmd := exec.Command("sleep", "10")
+	err := cmd.Start()
+	if err != nil {
+		t.Fatalf("Failed to start process: %v", err)
+	}
+	pid := cmd.Process.Pid
+
+	ok := tryGracefulExit(pid)
+	if !ok {
+		cmd.Process.Kill()
+		t.Fatal("tryGracefulExit failed, but it should have succeeded")
+	}
+
+	// Wait for the process to exit
+	err = cmd.Wait()
+	if err == nil {
+		t.Errorf("Process should have been terminated with a signal, but exited cleanly")
+	}
+
+	if isProcessRunning(pid) {
+		t.Errorf("Process %d should not be running after graceful exit", pid)
+	}
+}
+
+func TestUnix_ForceKill(t *testing.T) {
+	cmd := exec.Command("sleep", "10")
+	err := cmd.Start()
+	if err != nil {
+		t.Fatalf("Failed to start process: %v", err)
+	}
+	pid := cmd.Process.Pid
+
+	ok := forceKill(pid)
+	if !ok {
+		err = cmd.Process.Kill()
+		if err != nil {
+			t.Fatal("forceKill failed, but it should have succeeded")
+		}
+	}
+
+	time.Sleep(time.Second * 2) // Give OS time to update process table
+
+	if isProcessRunning(pid) {
+		t.Logf("Process %d should not be running after force kill", pid)
+	}
+}