feat: ShutdownException for background workers

Adds FrankenPHP\ShutdownException to gracefully interrupt background
workers blocked in C-level calls (sleep, Redis subscribe, etc.).

On POSIX, pthread_kill(SIGUSR1) interrupts the blocked syscall with
EINTR. The signal handler sets EG(vm_interrupt), causing the Zend VM
to throw ShutdownException at the next opcode boundary.

On Windows, CancelSynchronousIo() interrupts blocked I/O and the
shutdown flag triggers the same exception path.

PHP code catches it with try/catch - no new API, no callback:

    try {
        $redis->subscribe([...], function ($msg) { ... });
    } catch (\FrankenPHP\ShutdownException) {
        return Command::SUCCESS;
    }

Author: nicolas-grekas

background_worker.go

@@ -20,6 +20,13 @@ type backgroundWorkerState struct {
 	readyOnce   sync.Once
 }
 
+// reset prepares the state for a worker restart: new ready channel so
+// get_vars blocks until the restarted worker calls set_vars again.
+func (s *backgroundWorkerState) reset() {
+	s.ready = make(chan struct{})
+	s.readyOnce = sync.Once{}
+}
+
 type BackgroundWorkerRegistry struct {
 	entrypoint string
 	num        int // threads per background worker (0 = lazy-start with 1 thread)

caddy/module.go

@@ -45,6 +45,7 @@ type FrankenPHPModule struct {
 	Env map[string]string `json:"env,omitempty"`
 	// Workers configures the worker scripts to start.
 	Workers []workerConfig `json:"workers,omitempty"`
+
 	resolvedDocumentRoot        string
 	preparedEnv                 frankenphp.PreparedEnv
 	preparedEnvNeedsReplacement bool

caddy/workerconfig.go

@@ -13,7 +13,6 @@ import (
 	"github.com/dunglas/frankenphp/internal/fastabs"
 )
 
-
 // workerConfig represents the "worker" directive in the Caddyfile
 // it can appear in the "frankenphp", "php_server" and "php" directives
 //
@@ -42,13 +41,14 @@ type workerConfig struct {
 	MatchPath []string `json:"match_path,omitempty"`
 	// MaxConsecutiveFailures sets the maximum number of consecutive failures before panicking (defaults to 6, set to -1 to never panick)
 	MaxConsecutiveFailures int `json:"max_consecutive_failures,omitempty"`
+
 	// Background marks this worker as a background worker (non-HTTP)
 	Background         bool `json:"background,omitempty"`
 	backgroundRegistry *frankenphp.BackgroundWorkerRegistry
-	options          []frankenphp.WorkerOption
-	requestOptions   []frankenphp.RequestOption
-	absFileName      string
-	matchRelPath     string // pre-computed relative URL path for fast matching
+	options            []frankenphp.WorkerOption
+	requestOptions     []frankenphp.RequestOption
+	absFileName        string
+	matchRelPath       string // pre-computed relative URL path for fast matching
 }
 
 func unmarshalWorker(d *caddyfile.Dispenser) (workerConfig, error) {
@@ -136,6 +136,7 @@ func unmarshalWorker(d *caddyfile.Dispenser) (workerConfig, error) {
 			if err := caddyMatchPath.Provision(caddy.Context{}); err != nil {
 				return wc, d.WrapErr(err)
 			}
+
 			wc.MatchPath = caddyMatchPath
 		case "max_consecutive_failures":
 			if !d.NextArg() {

docs/background-workers.md

@@ -36,15 +36,15 @@ example.com {
 
 - `num` and `max_threads` are accepted but capped at 1 for now (pooling is a future feature). Values > 1 are rejected with a clear error.
 - `max_threads` on catch-all workers sets a safety cap for lazy-started instances (defaults to 16).
-- `max_consecutive_failures` defaults to -1 (never panic on boot failures).
+- `max_consecutive_failures` defaults to 6 (same as HTTP workers).
 - `env` and `watch` work the same as HTTP workers.
 
 ### Thread reservation
 
 Background workers get dedicated thread slots outside the global `max_threads` budget.
-They don't compete with HTTP auto-scaling. For catch-all workers, `max_threads` determines
-the reservation (default 16). Named workers with `num 0` (default) are lazy-started and
-don't reserve threads.
+They don't compete with HTTP auto-scaling. Named workers reserve 1 thread each
+(`max_threads` defaults to `max(num, 1)`). For catch-all workers, `max_threads` determines
+the reservation (default 16).
 
 Each `php_server` block has its own isolated background worker scope.
 
@@ -83,39 +83,28 @@ Objects, resources, and references are rejected.
 - Throws `RuntimeException` if not called from a background worker context
 - Throws `ValueError` if values contain objects, resources, or references
 
-### `frankenphp_worker_get_signaling_stream(): resource`
+### Shutdown: `FrankenPHP\ShutdownException`
 
-Returns a readable stream used for receiving signals from FrankenPHP.
-Signals are newline-terminated strings: `"stop\n"` signals shutdown or restart.
-Read with `fgets()` to identify the signal type.
+When FrankenPHP needs to stop a background worker (server shutdown, worker restart, file watcher trigger), it throws a `FrankenPHP\ShutdownException`. This exception interrupts any blocking PHP call - `sleep()`, `stream_select()`, Redis `subscribe()`, etc.
 
-Use `stream_select()` instead of `sleep()` or `usleep()` to wait between iterations:
+Use `try/catch` to handle shutdown gracefully:
 
 ```php
-function background_worker_should_stop(float $timeout = 0): bool
-{
-    static $signalingStream;
-    $signalingStream ??= frankenphp_worker_get_signaling_stream();
-    $s = (int) $timeout;
-
-    return match (@stream_select(...[[$signalingStream], [], [], $s, (int) (($timeout - $s) * 1e6)])) {
-        0 => false, // timeout
-        false => true, // error (pipe closed) = stop
-        default => "stop\n" === fgets($signalingStream),
-    };
+try {
+    $redis->subscribe(['+switch-master'], function ($msg) {
+        frankenphp_worker_set_vars([...]);
+    });
+} catch (\FrankenPHP\ShutdownException) {
+    // cleanup, close connections, etc.
 }
-
-do {
-    // ... do work, call set_vars() ...
-} while (!background_worker_should_stop(5));
 ```
 
-> [!WARNING]
-> Avoid using `sleep()` or `usleep()` in background workers. They block at the C level and cannot be interrupted.
-> A background worker using `sleep(60)` would delay shutdown or worker restart by up to 60 seconds.
-> Use `stream_select()` with the signaling stream instead - it wakes up immediately when FrankenPHP needs the thread to stop.
+If the exception is not caught, the script ends and the worker restarts normally.
 
-- Throws `RuntimeException` if not called from a background worker context
+> [!NOTE]
+> On POSIX, shutdown is implemented via `pthread_kill(SIGUSR1)` which interrupts blocking syscalls with `EINTR`.
+> On Windows, `CancelSynchronousIo` + `QueueUserAPC` interrupts blocking I/O and alertable waits (`SleepEx`).
+> In both cases, the Zend VM throws `ShutdownException` at the next opcode boundary.
 
 ## Example
 
@@ -134,27 +123,30 @@ match ($command) {
     default => throw new \RuntimeException("Unknown background worker: $command"),
 };
 
-function background_worker_should_stop(float $timeout = 0): bool
-{
-    static $signalingStream;
-    $signalingStream ??= frankenphp_worker_get_signaling_stream();
-    $s = (int) $timeout;
-
-    return 0 !== stream_select(...[[$signalingStream], [], [], $s, (int) (($timeout - $s) * 1e6)]);
-};
-
 function run_redis_watcher(): void
 {
     $sentinel = new \Redis();
     $sentinel->pconnect('sentinel-host', 26379);
 
-    do {
-        $master = $sentinel->rawCommand('SENTINEL', 'get-master-addr-by-name', 'mymaster');
-        frankenphp_worker_set_vars([
-            'MASTER_HOST' => $master[0],
-            'MASTER_PORT' => $master[1],
-        ]);
-    } while (!background_worker_should_stop(5.0)); // check every 5s
+    // Publish initial state
+    $master = $sentinel->rawCommand('SENTINEL', 'get-master-addr-by-name', 'mymaster');
+    frankenphp_worker_set_vars([
+        'MASTER_HOST' => $master[0],
+        'MASTER_PORT' => $master[1],
+    ]);
+
+    // subscribe() blocks until interrupted by ShutdownException
+    try {
+        $sentinel->subscribe(['+switch-master'], function ($r, $ch, $msg) {
+            [$name, $oldIp, $oldPort, $newIp, $newPort] = explode(' ', $msg);
+            frankenphp_worker_set_vars([
+                'MASTER_HOST' => $newIp,
+                'MASTER_PORT' => $newPort,
+            ]);
+        });
+    } catch (\FrankenPHP\ShutdownException) {
+        // graceful shutdown
+    }
 }
 ```
 
@@ -198,13 +190,10 @@ if (function_exists('frankenphp_worker_get_vars')) {
 - `$_SERVER['FRANKENPHP_WORKER_BACKGROUND']` is `true` for background workers, `false` for HTTP workers
 - Background workers also get `$_SERVER['argv']` = `[entrypoint, name]` for CLI compatibility
 - Crash recovery: automatic restart with exponential backoff
-- Graceful shutdown via `frankenphp_worker_get_signaling_stream()` and `stream_select()`
+- Graceful shutdown via `FrankenPHP\ShutdownException` - interrupts any blocking call
 - Worker restarts stop running background workers; the next `get_vars()` call starts them again
 - Use `error_log()` or `frankenphp_log()` for logging - avoid `echo`
 
-For advanced use cases (amphp, ReactPHP), the signaling stream can be registered directly
-in the event loop - see `frankenphp_worker_get_signaling_stream()`.
-
 ## Performance
 
 `get_vars` is designed to be called on every HTTP request with minimal overhead: