feat: cross-platform force-kill primitive for stuck PHP threads

Introduces a small, self-contained primitive that unblocks a PHP thread
stuck in a blocking call (sleep, synchronous I/O, etc.) so the graceful
drain used by RestartWorkers and DrainWorkers can make progress instead
of waiting for the block to return on its own. The primitive is useful
on its own and gives follow-up graceful-shutdown work a reviewed
foundation to build on.

- frankenphp.c: add frankenphp_init_force_kill / frankenphp_save_php_timer
  / frankenphp_force_kill_thread / frankenphp_destroy_force_kill. The
  per-thread PHP timer handle (Linux/FreeBSD ZTS) or OS thread handle
  (Windows) is captured at thread boot and stored in a pre-sized array
  so the kill path can fire from any goroutine without touching
  per-thread PHP state. Linux/FreeBSD arm PHP's max_execution_time timer
  (delivers SIGALRM -> "Maximum execution time exceeded"); Windows uses
  CancelSynchronousIo + QueueUserAPC to interrupt I/O and alertable
  waits; macOS and other platforms are a safe no-op (the thread is
  abandoned and exits when the blocking call returns naturally).

- phpmainthread.go: wire frankenphp_init_force_kill into initPHPThreads
  (sized to maxThreads, matching the thread_metrics allocation) and
  frankenphp_destroy_force_kill into drainPHPThreads.

- worker.go: add a 5-second graceful-drain grace period to
  drainWorkerThreads. Once elapsed, arm the force-kill primitive on any
  thread still outside Yielding and keep waiting on ready.Wait(); the
  kill lets the thread return from its blocking call so the drain
  completes in bounded time instead of hanging.

- worker_test.go + testdata/worker-sleep.php: TestRestartWorkersForceKillsStuckThread
  drives the path end-to-end. A worker blocks inside sleep(60) below
  frankenphp_handle_request (so drainChan close can't reach it); the
  test asserts RestartWorkers returns within 8s (grace + slack). The
  test skips on platforms without the underlying primitive.

Author: nicolas-grekas

caddy/admin.go

@@ -39,7 +39,13 @@ func (admin *FrankenPHPAdmin) restartWorkers(w http.ResponseWriter, r *http.Requ
 		return admin.error(http.StatusMethodNotAllowed, fmt.Errorf("method not allowed"))
 	}
 
-	frankenphp.RestartWorkers()
+	if err := frankenphp.RestartWorkers(); err != nil {
+		// Restart is incomplete: at least one worker thread was stuck in
+		// an uninterruptible blocking call and did not reload code. Do
+		// not let the admin endpoint lie to automation with a 200.
+		caddy.Log().Sugar().Errorf("workers restart incomplete: %v", err)
+		return admin.error(http.StatusInternalServerError, err)
+	}
 	caddy.Log().Info("workers restarted from admin api")
 	admin.success(w, "workers restarted successfully\n")
 

frankenphp.c

@@ -92,6 +92,135 @@ static bool is_forked_child = false;
 static void frankenphp_fork_child(void) { is_forked_child = true; }
 #endif
 
+/* Best-effort force-kill for PHP threads after the graceful-drain grace
+ * period. Each thread captures pointers to its own executor_globals'
+ * vm_interrupt and timed_out atomic bools at boot and hands them back to
+ * Go via go_frankenphp_store_force_kill_slot. From any goroutine, the
+ * Go side passes that slot back to frankenphp_force_kill_thread, which
+ * stores true into both bools, waking the VM at the next opcode boundary
+ * and unwinding the thread through zend_timeout().
+ *
+ * On platforms with POSIX realtime signals (Linux, FreeBSD), force-kill
+ * also delivers SIGRTMIN+3 to the target thread so any in-flight blocking
+ * syscall (select, sleep, nanosleep, blocking I/O without SA_RESTART)
+ * returns EINTR and the VM gets a chance to observe the atomic bools on
+ * the next opcode. On Windows, CancelSynchronousIo + QueueUserAPC does
+ * the equivalent for alertable I/O and SleepEx. Non-alertable Sleep()
+ * (including PHP's usleep on Windows) stays uninterruptible - the VM
+ * must wait for it to return naturally before bailing.
+ *
+ * macOS has no realtime signals exposed to user-space, so the atomic
+ * bool path is the only mechanism there: threads busy-looping in PHP
+ * are killed promptly, threads stuck in blocking syscalls wait to
+ * return on their own.
+ *
+ * JIT caveat: when the OPcache JIT is enabled, some hot code paths do
+ * not check vm_interrupt between opcodes. A thread stuck in a
+ * JIT-compiled busy loop may not observe the atomic-bool store at all
+ * (see https://github.com/php/php-src/issues/21267). The syscall-
+ * interruption path (signal -> EINTR) still works since the kernel
+ * wakes the thread regardless of JIT state, so the regression surface
+ * is pure-PHP busy loops under JIT. Those fall through to the abandon
+ * path after forceKillDeadline.
+ *
+ * Signal number reservation: SIGRTMIN+3 is reserved by FrankenPHP for
+ * force-kill. If a PHP user script registers its own handler via
+ * pcntl_signal(SIGRTMIN+3, ...), it clobbers ours and force-kill stops
+ * working for threads it runs on. Projects embedding FrankenPHP
+ * alongside their own Go code that also uses that signal must choose a
+ * different one here. Keep this in mind if ever changing the constant.
+ *
+ * The slot lives in the Go-side phpThread struct - there is no C-side
+ * array or init/destroy dance. Signal handler installation happens once
+ * via pthread_once the first time a thread registers. */
+#ifdef PHP_WIN32
+static void CALLBACK frankenphp_noop_apc(ULONG_PTR param) { (void)param; }
+#endif
+
+#ifdef FRANKENPHP_HAS_KILL_SIGNAL
+/* No-op handler: signal delivery is sufficient on its own because it
+ * forces the in-flight syscall to return EINTR. The VM then observes
+ * vm_interrupt on the next opcode and unwinds via zend_timeout(). */
+static void frankenphp_kill_signal_handler(int sig) { (void)sig; }
+
+static pthread_once_t kill_signal_handler_installed = PTHREAD_ONCE_INIT;
+static void install_kill_signal_handler(void) {
+  /* Install the no-op handler process-wide with SA_RESTART cleared so
+   * blocking syscalls return EINTR when the signal is delivered rather
+   * than being transparently restarted by libc. SA_ONSTACK is set
+   * defensively: the signal targets non-Go pthreads via pthread_kill,
+   * but if it's ever delivered to a Go-managed thread (e.g. through
+   * accidental process-level raise), Go requires the handler to run on
+   * the alternate signal stack to avoid corrupting the goroutine's. */
+  struct sigaction sa;
+  memset(&sa, 0, sizeof(sa));
+  sa.sa_handler = frankenphp_kill_signal_handler;
+  sigemptyset(&sa.sa_mask);
+  sa.sa_flags = SA_ONSTACK;
+  sigaction(FRANKENPHP_KILL_SIGNAL, &sa, NULL);
+}
+#endif
+
+/* Called by each PHP thread at boot, from its own TSRM context, so that
+ * the EG-backed addresses resolve to the thread's private executor_globals
+ * and the captured thread identity refers to itself. Hands the slot to
+ * the Go side via go_frankenphp_store_force_kill_slot; the slot's
+ * lifetime is the phpThread's. */
+void frankenphp_register_thread_for_kill(uintptr_t idx) {
+  force_kill_slot slot;
+  memset(&slot, 0, sizeof(slot));
+  slot.vm_interrupt = &EG(vm_interrupt);
+  slot.timed_out = &EG(timed_out);
+#ifdef FRANKENPHP_HAS_KILL_SIGNAL
+  slot.tid = pthread_self();
+  pthread_once(&kill_signal_handler_installed, install_kill_signal_handler);
+#elif defined(PHP_WIN32)
+  if (!DuplicateHandle(GetCurrentProcess(), GetCurrentThread(),
+                       GetCurrentProcess(), &slot.thread_handle, 0, FALSE,
+                       DUPLICATE_SAME_ACCESS)) {
+    /* DuplicateHandle can fail under resource pressure; leave the handle
+     * NULL so force_kill_thread falls back to the atomic-bool path only. */
+    slot.thread_handle = NULL;
+  }
+#endif
+  go_frankenphp_store_force_kill_slot(idx, slot);
+}
+
+void frankenphp_force_kill_thread(force_kill_slot slot) {
+  if (slot.vm_interrupt == NULL) {
+    /* Thread never reached register_thread_for_kill (aborted during boot). */
+    return;
+  }
+  /* Set the atomic bools first so that by the time the thread wakes up -
+   * whether from our signal/APC or naturally - the VM sees them and
+   * routes through zend_timeout() -> "Maximum execution time exceeded". */
+  zend_atomic_bool_store(slot.timed_out, true);
+  zend_atomic_bool_store(slot.vm_interrupt, true);
+
+#ifdef FRANKENPHP_HAS_KILL_SIGNAL
+  /* Return value intentionally ignored: ESRCH (thread already exited) and
+   * EINVAL are both benign - there is simply nothing to unblock. */
+  pthread_kill(slot.tid, FRANKENPHP_KILL_SIGNAL);
+#elif defined(PHP_WIN32)
+  if (slot.thread_handle != NULL) {
+    CancelSynchronousIo(slot.thread_handle);
+    QueueUserAPC((PAPCFUNC)frankenphp_noop_apc, slot.thread_handle, 0);
+  }
+#endif
+}
+
+/* Releases any OS resource tied to the slot (currently: CloseHandle on
+ * Windows). Called by the Go side when a phpThread is torn down. */
+void frankenphp_release_thread_for_kill(force_kill_slot slot) {
+#ifdef PHP_WIN32
+  if (slot.thread_handle != NULL) {
+    CloseHandle(slot.thread_handle);
+  }
+#else
+  (void)slot;
+#endif
+}
+
 void frankenphp_update_local_thread_context(bool is_worker) {
   is_worker_thread = is_worker;
 
@@ -1073,6 +1202,11 @@ static void *php_thread(void *arg) {
 #endif
 #endif
 
+  /* Register this thread's vm_interrupt/timed_out addresses so the Go side
+   * can force-kill it after the graceful-drain grace period if it gets stuck
+   * in a busy PHP loop. */
+  frankenphp_register_thread_for_kill(thread_index);
+
   bool thread_is_healthy = true;
   bool has_attempted_shutdown = false;
 
@@ -1150,6 +1284,15 @@ static void *php_thread(void *arg) {
   }
   zend_end_try();
 
+  /* Clear the force-kill slot BEFORE ts_free_thread: that call frees
+   * the TSRM storage that &EG(vm_interrupt) / &EG(timed_out) point at.
+   * Clearing afterwards (even under a write lock) would leave a window
+   * where a concurrent delivery reads the still-populated slot and
+   * writes into freed memory. Applies to both the healthy exit and the
+   * unhealthy-restart path below so every call to force_kill_thread
+   * sees either a valid or a zero-valued slot. */
+  go_frankenphp_clear_force_kill_slot(thread_index);
+
   /* free all global PHP memory reserved for this thread */
 #ifdef ZTS
   ts_free_thread();

frankenphp.h

@@ -46,6 +46,28 @@ static inline HRESULT LongLongSub(LONGLONG llMinuend, LONGLONG llSubtrahend,
 #include <stdbool.h>
 #include <stdint.h>
 
+#ifndef PHP_WIN32
+#include <pthread.h>
+#include <signal.h>
+#endif
+
+/* Platform capabilities for the force-kill primitive; declared in the
+ * header so Go (via CGo) gets the correct struct layout too. */
+#if !defined(PHP_WIN32) && defined(SIGRTMIN)
+#define FRANKENPHP_HAS_KILL_SIGNAL 1
+#define FRANKENPHP_KILL_SIGNAL (SIGRTMIN + 3)
+#endif
+
+typedef struct {
+  zend_atomic_bool *vm_interrupt;
+  zend_atomic_bool *timed_out;
+#ifdef FRANKENPHP_HAS_KILL_SIGNAL
+  pthread_t tid;
+#elif defined(PHP_WIN32)
+  HANDLE thread_handle;
+#endif
+} force_kill_slot;
+
 #ifndef FRANKENPHP_VERSION
 #define FRANKENPHP_VERSION dev
 #endif
@@ -193,6 +215,18 @@ void frankenphp_init_thread_metrics(int max_threads);
 void frankenphp_destroy_thread_metrics(void);
 size_t frankenphp_get_thread_memory_usage(uintptr_t thread_index);
 
+/* Best-effort force-kill primitives. The slot is populated by each PHP
+ * thread at boot (frankenphp_register_thread_for_kill calls back into Go
+ * via go_frankenphp_store_force_kill_slot) and lives in the Go-side
+ * phpThread. force_kill_thread interrupts the Zend VM at the next opcode
+ * boundary; on POSIX it also delivers SIGRTMIN+3 to the target thread,
+ * on Windows it calls CancelSynchronousIo + QueueUserAPC. release_thread
+ * drops any OS-owned resource tied to the slot (currently the Windows
+ * thread handle). */
+void frankenphp_register_thread_for_kill(uintptr_t thread_index);
+void frankenphp_force_kill_thread(force_kill_slot slot);
+void frankenphp_release_thread_for_kill(force_kill_slot slot);
+
 void register_extensions(zend_module_entry **m, int len);
 
 #endif

phpmainthread.go

@@ -97,6 +97,14 @@ func drainPHPThreads() {
 	}
 
 	doneWG.Wait()
+	// Slots are released by the PHP threads themselves, under the
+	// per-thread write lock, right before ts_free_thread() runs (see
+	// go_frankenphp_clear_force_kill_slot). A second release here would
+	// be a double-CloseHandle on Windows (potentially on a reused handle)
+	// and bypass the lock discipline on every platform, so we rely on
+	// the thread-exit path instead. Threads that were abandoned by
+	// phpThread.shutdown() still hold their slot; the OS reclaims the
+	// handle when the process exits.
 	mainThread.state.Set(state.Done)
 	mainThread.state.WaitFor(state.Reserved)
 	C.frankenphp_destroy_thread_metrics()

phpthread.go

@@ -5,9 +5,11 @@ package frankenphp
 import "C"
 import (
 	"context"
+	"log/slog"
 	"runtime"
 	"sync"
 	"sync/atomic"
+	"time"
 	"unsafe"
 
 	"github.com/dunglas/frankenphp/internal/state"
@@ -25,6 +27,26 @@ type phpThread struct {
 	contextMu    sync.RWMutex
 	state        *state.ThreadState
 	requestCount atomic.Int64
+	// forceKill is populated by go_frankenphp_store_force_kill_slot from
+	// the PHP thread's own TSRM context at boot. Read by other goroutines
+	// via RestartWorkers/DrainWorkers; forceKillMu serialises reads with
+	// the thread-shutdown clear path so a concurrent force-kill cannot
+	// dereference the captured &EG() pointers after ts_free_thread() has
+	// freed the underlying TSRM memory on the PHP thread.
+	forceKillMu sync.RWMutex
+	forceKill   C.force_kill_slot
+}
+
+// forceKillLocked stores true into the vm_interrupt/timed_out atomic
+// bools of the target thread and, on platforms that support it,
+// delivers a wake-up signal. The read lock serialises with
+// go_frankenphp_on_thread_shutdown, which clears the slot before
+// ts_free_thread() runs; without the lock a racing delivery could
+// write into freed TSRM memory.
+func (thread *phpThread) forceKillLocked() {
+	thread.forceKillMu.RLock()
+	defer thread.forceKillMu.RUnlock()
+	C.frankenphp_force_kill_thread(thread.forceKill)
 }
 
 // threadHandler defines how the callbacks from the C thread should be handled
@@ -93,7 +115,30 @@ func (thread *phpThread) shutdown() {
 	}
 
 	close(thread.drainChan)
-	thread.state.WaitFor(state.Done)
+
+	// Bounded wait: grace period, then force-kill, then abandon. Without
+	// this, a thread stuck in an uninterruptible blocking syscall (e.g.
+	// PHP usleep on Windows, any syscall on macOS where force-kill is a
+	// no-op) would hang Shutdown forever.
+	done := make(chan struct{})
+	go func() {
+		thread.state.WaitFor(state.Done)
+		close(done)
+	}()
+	select {
+	case <-done:
+	case <-time.After(drainGracePeriod):
+		thread.forceKillLocked()
+		select {
+		case <-done:
+		case <-time.After(forceKillDeadline):
+			if globalLogger.Enabled(globalCtx, slog.LevelWarn) {
+				globalLogger.LogAttrs(globalCtx, slog.LevelWarn,
+					"PHP thread did not exit after force-kill; abandoning to unblock Shutdown")
+			}
+		}
+	}
+
 	thread.drainChan = make(chan struct{})
 
 	// threads go back to the reserved state from which they can be booted again
@@ -203,10 +248,44 @@ func go_frankenphp_after_script_execution(threadIndex C.uintptr_t, exitStatus C.
 	thread.Unpin()
 }
 
+//export go_frankenphp_store_force_kill_slot
+func go_frankenphp_store_force_kill_slot(threadIndex C.uintptr_t, slot C.force_kill_slot) {
+	thread := phpThreads[threadIndex]
+	// Take the write lock: an unhealthy-restart respawn races a concurrent
+	// RestartWorkers/Shutdown that reads the slot under RLock. Without
+	// this lock, the release+overwrite below could race with a reader
+	// and/or tear the struct mid-write.
+	thread.forceKillMu.Lock()
+	// Release any resource (Windows thread HANDLE) tied to the previous
+	// slot: a phpThread can reboot (max_requests, unhealthy restart) and
+	// register a fresh DuplicateHandle each time.
+	C.frankenphp_release_thread_for_kill(thread.forceKill)
+	thread.forceKill = slot
+	thread.forceKillMu.Unlock()
+}
+
+//export go_frankenphp_clear_force_kill_slot
+func go_frankenphp_clear_force_kill_slot(threadIndex C.uintptr_t) {
+	// Called from C right before ts_free_thread() on both the healthy
+	// and unhealthy thread-exit paths. Clearing the slot here (rather
+	// than in on_thread_shutdown, which runs after ts_free_thread) means
+	// the &EG(vm_interrupt) / &EG(timed_out) pointers are swapped out
+	// for nils BEFORE the TSRM storage they point at is freed, so any
+	// concurrent force-kill delivery either ran to completion before we
+	// took the write lock, or sees a zero-valued slot and early-returns.
+	thread := phpThreads[threadIndex]
+	thread.forceKillMu.Lock()
+	C.frankenphp_release_thread_for_kill(thread.forceKill)
+	thread.forceKill = C.force_kill_slot{}
+	thread.forceKillMu.Unlock()
+}
+
 //export go_frankenphp_on_thread_shutdown
 func go_frankenphp_on_thread_shutdown(threadIndex C.uintptr_t) {
 	thread := phpThreads[threadIndex]
 	thread.Unpin()
+	// Force-kill slot is already cleared by go_frankenphp_clear_force_kill_slot
+	// before ts_free_thread; nothing to do here except the state signal.
 	if thread.state.Is(state.Rebooting) {
 		thread.state.Set(state.RebootReady)
 	} else {

testdata/worker-sleep.php

@@ -0,0 +1,21 @@
+<?php
+
+// Worker that sleeps inside the handler to simulate a stuck request blocking
+// drain. Used to test the force-kill grace period.
+//
+// Before sleeping we touch a marker file whose path is passed via the
+// SLEEP_MARKER header. The Go test polls for the file so it only arms
+// RestartWorkers once the worker is proven to be inside sleep(), removing
+// the fixed-time race of a bare time.Sleep on the caller side.
+$fn = static function () {
+    $marker = $_SERVER['HTTP_SLEEP_MARKER'] ?? '';
+    if ($marker !== '') {
+        @touch($marker);
+    }
+    sleep(60);
+    echo 'should not reach';
+};
+
+do {
+    $ret = \frankenphp_handle_request($fn);
+} while ($ret);

watcher.go

@@ -3,6 +3,7 @@
 package frankenphp
 
 import (
+	"log/slog"
 	"sync/atomic"
 
 	"github.com/dunglas/frankenphp/internal/watcher"
@@ -33,7 +34,9 @@ func initWatchers(o *opt) error {
 		watchPatterns = append(watchPatterns, &watcher.PatternGroup{
 			Callback: func(_ []*watcherGo.Event) {
 				if restartWorkers.Swap(false) {
-					RestartWorkers()
+					if err := RestartWorkers(); err != nil && globalLogger.Enabled(globalCtx, slog.LevelError) {
+						globalLogger.LogAttrs(globalCtx, slog.LevelError, "watcher-triggered restart incomplete", slog.String("err", err.Error()))
+					}
 				}
 			},
 		})