PHP-FPM recycles worker processes after a configurable number of
requests (`pm.max_requests`), preventing memory leaks from accumulating
over time. FrankenPHP keeps PHP threads alive indefinitely, so any leak
in PHP extensions (e.g. ZTS builds of profiling tools like Blackfire) or
application code compounds over hours/days. In production behind reverse
proxies like Cloudflare, this can lead to gradual resource exhaustion
and eventually 502 errors with no visible warnings in logs.
This PR adds a `max_requests` option in the global `frankenphp` block
that automatically restarts PHP threads after a given number of
requests, fully cleaning up the thread's memory and state. It applies to
both regular (module mode) and worker threads.
When a thread reaches the limit it exits the C thread loop, triggering a
full cleanup including any memory leaked by extensions. A fresh thread
is then booted transparently. Other threads continue serving requests
during the restart.
This cannot be done from userland PHP: restarting a worker script from
PHP only resets PHP-level state, not the underlying C thread-local
storage where extension-level leaks accumulate. And in module mode
(without workers), there is no userland loop to count requests at all.
Default is `0` (unlimited), preserving existing behavior.
Usage:
```caddyfile
{
frankenphp {
max_requests 500
}
}
```
Changes:
- New `max_requests` Caddyfile directive in the global `frankenphp`
block
- New `WithMaxRequests` functional option
- New `Rebooting` and `RebootReady` states in the thread state machine
for restart coordination
- Regular thread restart in `threadregular.go`
- Worker thread restart in `threadworker.go`
- Safe shutdown: `shutdown()` waits for in-flight reboots to complete
before draining threads
- Tests for both module and worker mode (sequential and concurrent),
with debug log verification
- Updated docs
This PR uses `zend_array_dup` to simplify and optimize the environment sandboxing
logic. It also guarantees no environment leakage on FrankenPHP restarts.
This PR:
- moves state.go to its own module
- moves the phpheaders test the phpheaders module
- simplifies backoff.go
- makes the backoff error instead of panic (so it can be tested)
- removes some unused C structs
* Decouple workers.
* Moves code to separate file.
* Cleans up the exponential backoff.
* Initial working implementation.
* Refactors php threads to take callbacks.
* Cleanup.
* Cleanup.
* Cleanup.
* Cleanup.
* Adjusts watcher logic.
* Adjusts the watcher logic.
* Fix opcache_reset race condition.
* Fixing merge conflicts and formatting.
* Prevents overlapping of TSRM reservation and script execution.
* Adjustments as suggested by @dunglas.
* Adds error assertions.
* Adds comments.
* Removes logs and explicitly compares to C.false.
* Resets check.
* Adds cast for safety.
* Fixes waitgroup overflow.
* Resolves waitgroup race condition on startup.
* Moves worker request logic to worker.go.
* Removes defer.
* Removes call from go to c.
* Fixes merge conflict.
* Adds fibers test back in.
* Refactors new thread loop approach.
* Removes redundant check.
* Adds compareAndSwap.
* Refactor: removes global waitgroups and uses a 'thread state' abstraction instead.
* Removes unnecessary method.
* Updates comment.
* Removes unnecessary booleans.
* test
* First state machine steps.
* Splits threads.
* Minimal working implementation with broken tests.
* Fixes tests.
* Refactoring.
* Fixes merge conflicts.
* Formatting
* C formatting.
* More cleanup.
* Allows for clean state transitions.
* Adds state tests.
* Adds support for thread transitioning.
* Fixes the testdata path.
* Formatting.
* Allows transitioning back to inactive state.
* Fixes go linting.
* Formatting.
* Removes duplication.
* Applies suggestions by @dunglas
* Removes redundant check.
* Locks the handler on restart.
* Removes unnecessary log.
* Changes Unpin() logic as suggested by @withinboredom
* Adds suggestions by @dunglas and resolves TODO.
* Makes restarts fully safe.
* Will make the initial startup fail even if the watcher is enabled (as is currently the case)
* Also adds compareAndSwap to the test.
* Adds comment.
* Prevents panic on initial watcher startup.
Nicolas Grekas