feat: Add configurable max_requests for PHP threads

Author: nicolas-grekas

caddy/app.go

@@ -57,6 +57,8 @@ type FrankenPHPApp struct {
 	MaxWaitTime time.Duration `json:"max_wait_time,omitempty"`
 	// The maximum amount of time an autoscaled thread may be idle before being deactivated
 	MaxIdleTime time.Duration `json:"max_idle_time,omitempty"`
+	// MaxRequests sets the maximum number of requests a regular (non-worker) PHP thread handles before restarting (0 = unlimited)
+	MaxRequests int `json:"max_requests,omitempty"`
 
 	opts    []frankenphp.Option
 	metrics frankenphp.Metrics
@@ -153,6 +155,7 @@ func (f *FrankenPHPApp) Start() error {
 		frankenphp.WithPhpIni(f.PhpIni),
 		frankenphp.WithMaxWaitTime(f.MaxWaitTime),
 		frankenphp.WithMaxIdleTime(f.MaxIdleTime),
+		frankenphp.WithMaxRequests(f.MaxRequests),
 	)
 
 	for _, w := range f.Workers {
@@ -192,6 +195,7 @@ func (f *FrankenPHPApp) Stop() error {
 	f.NumThreads = 0
 	f.MaxWaitTime = 0
 	f.MaxIdleTime = 0
+	f.MaxRequests = 0
 
 	optionsMU.Lock()
 	options = nil
@@ -255,6 +259,17 @@ func (f *FrankenPHPApp) UnmarshalCaddyfile(d *caddyfile.Dispenser) error {
 				}
 
 				f.MaxIdleTime = v
+			case "max_requests":
+				if !d.NextArg() {
+					return d.ArgErr()
+				}
+
+				v, err := strconv.ParseUint(d.Val(), 10, 32)
+				if err != nil {
+					return d.WrapErr(err)
+				}
+
+				f.MaxRequests = int(v)
 			case "php_ini":
 				parseIniLine := func(d *caddyfile.Dispenser) error {
 					key := d.Val()
@@ -311,7 +326,7 @@ func (f *FrankenPHPApp) UnmarshalCaddyfile(d *caddyfile.Dispenser) error {
 
 				f.Workers = append(f.Workers, wc)
 			default:
-				return wrongSubDirectiveError("frankenphp", "num_threads, max_threads, php_ini, worker, max_wait_time, max_idle_time", d.Val())
+				return wrongSubDirectiveError("frankenphp", "num_threads, max_threads, php_ini, worker, max_wait_time, max_idle_time, max_requests", d.Val())
 			}
 		}
 	}

docs/config.md

@@ -97,6 +97,7 @@ You can also explicitly configure FrankenPHP using the [global option](https://c
 		max_threads <num_threads> # Limits the number of additional PHP threads that can be started at runtime. Default: num_threads. Can be set to 'auto'.
 		max_wait_time <duration> # Sets the maximum time a request may wait for a free PHP thread before timing out. Default: disabled.
 		max_idle_time <duration> # Sets the maximum time an autoscaled thread may be idle before being deactivated. Default: 5s.
+		max_requests <num> # Sets the maximum number of requests a PHP thread will handle before being restarted, useful for mitigating memory leaks. Applies to both regular and worker threads. Default: 0 (unlimited). See below.
 		php_ini <key> <value> # Set a php.ini directive. Can be used several times to set multiple directives.
 		worker {
 			file <path> # Sets the path to the worker script.
@@ -190,6 +191,7 @@ php_server [<matcher>] {
 		watch <path> # Sets the path to watch for file changes. Can be specified more than once for multiple paths.
 		env <key> <value> # Sets an extra environment variable to the given value. Can be specified more than once for multiple environment variables. Environment variables for this worker are also inherited from the php_server parent, but can be overwritten here.
 		match <path> # match the worker to a path pattern. Overrides try_files and can only be used in the php_server directive.
+		max_requests <num> # Sets the maximum number of requests a worker thread will handle before restarting, useful for mitigating memory leaks. Default: 0 (unlimited).
 	}
 	worker <other_file> <num> # Can also use the short form like in the global frankenphp block.
 }
@@ -265,6 +267,29 @@ and otherwise forward the request to the worker matching the path pattern.
 }
 ```
 
+## Restarting Threads After a Number of Requests
+
+Similar to PHP-FPM's [`pm.max_requests`](https://www.php.net/manual/en/install.fpm.configuration.php#pm.max-requests),
+FrankenPHP can automatically restart PHP threads after they have handled a given number of requests.
+This is useful for mitigating memory leaks in PHP extensions or application code,
+since a restart fully cleans up the thread's memory and state.
+
+The `max_requests` setting in the global `frankenphp` block applies to all PHP threads (both regular and worker threads):
+
+```caddyfile
+{
+	frankenphp {
+		max_requests 500
+	}
+}
+```
+
+When a thread reaches the limit, the underlying C thread is fully restarted,
+cleaning up all ZTS thread-local storage, including any memory leaked by PHP extensions.
+Other threads continue to serve requests during the restart, so there is no downtime.
+
+Set to `0` (default) to disable the limit and let threads run indefinitely.
+
 ## Environment Variables
 
 The following environment variables can be used to inject Caddy directives in the `Caddyfile` without modifying it:

frankenphp.go

@@ -66,7 +66,8 @@ var (
 
 	metrics Metrics = nullMetrics{}
 
-	maxWaitTime time.Duration
+	maxWaitTime          time.Duration
+	maxRequestsPerThread int
 )
 
 type ErrRejected struct {
@@ -275,6 +276,7 @@ func Init(options ...Option) error {
 	}
 
 	maxWaitTime = opt.maxWaitTime
+	maxRequestsPerThread = opt.maxRequests
 
 	if opt.maxIdleTime > 0 {
 		maxIdleTime = opt.maxIdleTime
@@ -369,6 +371,13 @@ func Shutdown() {
 
 	drainWatchers()
 	drainAutoScaling()
+
+	// signal restart goroutines to stop spawning and wait for in-flight ones
+	shutdownInProgress.Store(true)
+	for restartingThreads.Load() > 0 {
+		runtime.Gosched()
+	}
+
 	drainPHPThreads()
 
 	metrics.Shutdown()
@@ -786,5 +795,7 @@ func resetGlobals() {
 	workersByPath = nil
 	watcherIsEnabled = false
 	maxIdleTime = defaultMaxIdleTime
+	maxRequestsPerThread = 0
+	shutdownInProgress.Store(false)
 	globalMu.Unlock()
 }

frankenphp_test.go

@@ -45,6 +45,7 @@ type testOptions struct {
 	realServer         bool
 	logger             *slog.Logger
 	initOpts           []frankenphp.Option
+	workerOpts         []frankenphp.WorkerOption
 	requestOpts        []frankenphp.RequestOption
 	phpIni             map[string]string
 }
@@ -66,6 +67,7 @@ func runTest(t *testing.T, test func(func(http.ResponseWriter, *http.Request), *
 			frankenphp.WithWorkerEnv(opts.env),
 			frankenphp.WithWorkerWatchMode(opts.watch),
 		}
+		workerOpts = append(workerOpts, opts.workerOpts...)
 		initOpts = append(initOpts, frankenphp.WithWorkers("workerName", testDataDir+opts.workerScript, opts.nbWorkers, workerOpts...))
 	}
 	initOpts = append(initOpts, opts.initOpts...)

maxrequests_regular_test.go

@@ -0,0 +1,128 @@
+package frankenphp_test
+
+import (
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/dunglas/frankenphp"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestModuleMaxRequests verifies that regular (non-worker) PHP threads restart
+// after reaching max_requests by checking debug logs for restart messages.
+func TestModuleMaxRequests(t *testing.T) {
+	const maxRequests = 5
+	const totalRequests = 30
+
+	var buf syncBuffer
+	logger := slog.New(slog.NewTextHandler(&buf, &slog.HandlerOptions{Level: slog.LevelDebug}))
+
+	runTest(t, func(_ func(http.ResponseWriter, *http.Request), ts *httptest.Server, _ int) {
+		require.NotNil(t, ts)
+		client := &http.Client{Timeout: 5 * time.Second}
+
+		for i := 0; i < totalRequests; i++ {
+			resp, err := client.Get(ts.URL + "/index.php")
+			require.NoError(t, err, "request %d should succeed", i)
+
+			body, err := io.ReadAll(resp.Body)
+			require.NoError(t, err)
+			_ = resp.Body.Close()
+
+			assert.Equal(t, 200, resp.StatusCode, "request %d should return 200, got body: %s", i, string(body))
+			assert.Contains(t, string(body), "I am by birth a Genevese",
+				"request %d should return correct body", i)
+		}
+
+		restartCount := strings.Count(buf.String(), "max requests reached, restarting thread")
+		t.Logf("Thread restarts observed: %d", restartCount)
+		assert.GreaterOrEqual(t, restartCount, 2,
+			"with maxRequests=%d and %d requests on 2 threads, at least 2 restarts should occur", maxRequests, totalRequests)
+	}, &testOptions{
+		realServer: true,
+		logger:     logger,
+		initOpts: []frankenphp.Option{
+			frankenphp.WithNumThreads(2),
+			frankenphp.WithMaxRequests(maxRequests),
+		},
+	})
+}
+
+// TestModuleMaxRequestsConcurrent verifies max_requests works under concurrent load
+// in module mode. All requests must succeed despite threads restarting.
+func TestModuleMaxRequestsConcurrent(t *testing.T) {
+	const maxRequests = 10
+	const totalRequests = 200
+	const concurrency = 20
+
+	runTest(t, func(_ func(http.ResponseWriter, *http.Request), ts *httptest.Server, _ int) {
+		require.NotNil(t, ts)
+		client := &http.Client{Timeout: 10 * time.Second}
+
+		var successCount int
+		var mu sync.Mutex
+		sem := make(chan struct{}, concurrency)
+		var wg sync.WaitGroup
+
+		for i := 0; i < totalRequests; i++ {
+			wg.Add(1)
+			sem <- struct{}{}
+			go func(i int) {
+				defer func() { <-sem; wg.Done() }()
+
+				resp, err := client.Get(ts.URL + "/index.php")
+				if err != nil {
+					return
+				}
+				body, _ := io.ReadAll(resp.Body)
+				_ = resp.Body.Close()
+
+				if resp.StatusCode == 200 && strings.Contains(string(body), "I am by birth a Genevese") {
+					mu.Lock()
+					successCount++
+					mu.Unlock()
+				}
+			}(i)
+		}
+		wg.Wait()
+
+		t.Logf("Success: %d/%d", successCount, totalRequests)
+		assert.GreaterOrEqual(t, successCount, int(totalRequests*0.95),
+			"at least 95%% of requests should succeed despite regular thread restarts")
+	}, &testOptions{
+		realServer: true,
+		initOpts: []frankenphp.Option{
+			frankenphp.WithNumThreads(8),
+			frankenphp.WithMaxRequests(maxRequests),
+		},
+	})
+}
+
+// TestModuleMaxRequestsZeroIsUnlimited verifies that max_requests=0 (default)
+// means threads never restart.
+func TestModuleMaxRequestsZeroIsUnlimited(t *testing.T) {
+	runTest(t, func(_ func(http.ResponseWriter, *http.Request), ts *httptest.Server, _ int) {
+		require.NotNil(t, ts)
+		client := &http.Client{Timeout: 5 * time.Second}
+
+		for i := 0; i < 50; i++ {
+			resp, err := client.Get(ts.URL + "/index.php")
+			require.NoError(t, err)
+			body, _ := io.ReadAll(resp.Body)
+			_ = resp.Body.Close()
+
+			assert.Equal(t, 200, resp.StatusCode)
+			assert.Contains(t, string(body), "I am by birth a Genevese")
+		}
+	}, &testOptions{
+		realServer: true,
+		initOpts:   []frankenphp.Option{frankenphp.WithNumThreads(2)},
+	})
+}