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,13 +155,15 @@ 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 {
 		w.options = append(w.options,
 			frankenphp.WithWorkerEnv(w.Env),
 			frankenphp.WithWorkerWatchMode(w.Watch),
 			frankenphp.WithWorkerMaxFailures(w.MaxConsecutiveFailures),
+			frankenphp.WithWorkerMaxRequests(w.MaxRequests),
 			frankenphp.WithWorkerMaxThreads(w.MaxThreads),
 			frankenphp.WithWorkerRequestOptions(w.requestOptions...),
 		)
@@ -192,6 +196,7 @@ func (f *FrankenPHPApp) Stop() error {
 	f.NumThreads = 0
 	f.MaxWaitTime = 0
 	f.MaxIdleTime = 0
+	f.MaxRequests = 0
 
 	optionsMU.Lock()
 	options = nil
@@ -255,6 +260,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 +327,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())
 			}
 		}
 	}

caddy/workerconfig.go

@@ -41,6 +41,8 @@ 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"`
+	// MaxRequests sets the maximum number of requests a worker thread will handle before restarting (0 = unlimited, similar to php-fpm's pm.max_requests)
+	MaxRequests int `json:"max_requests,omitempty"`
 
 	options        []frankenphp.WorkerOption
 	requestOptions []frankenphp.RequestOption
@@ -145,8 +147,19 @@ func unmarshalWorker(d *caddyfile.Dispenser) (workerConfig, error) {
 			}
 
 			wc.MaxConsecutiveFailures = v
+		case "max_requests":
+			if !d.NextArg() {
+				return wc, d.ArgErr()
+			}
+
+			v, err := strconv.ParseUint(d.Val(), 10, 32)
+			if err != nil {
+				return wc, d.WrapErr(err)
+			}
+
+			wc.MaxRequests = int(v)
 		default:
-			return wc, wrongSubDirectiveError("worker", "name, file, num, env, watch, match, max_consecutive_failures, max_threads", v)
+			return wc, wrongSubDirectiveError("worker", "name, file, num, env, watch, match, max_consecutive_failures, max_threads, max_requests", v)
 		}
 	}
 

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. 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.
@@ -105,6 +106,7 @@ You can also explicitly configure FrankenPHP using the [global option](https://c
 			watch <path> # Sets the path to watch for file changes. Can be specified more than once for multiple paths.
 			name <name> # Sets the name of the worker, used in logs and metrics. Default: absolute path of worker file
 			max_consecutive_failures <num> # Sets the maximum number of consecutive failures before the worker is considered unhealthy, -1 means the worker will always restart. Default: 6.
+			max_requests <num> # Sets the maximum number of requests a worker thread will handle before restarting, useful for mitigating memory leaks. Default: 0 (unlimited). See below.
 		}
 	}
 }
@@ -190,6 +192,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 +268,49 @@ 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 (including ZTS thread-local storage).
+
+### Module Mode (Without Workers)
+
+When not using workers, `max_requests` is set in the global `frankenphp` block and applies to all regular PHP threads:
+
+```caddyfile
+{
+	frankenphp {
+		max_requests 500
+	}
+}
+```
+
+When a thread reaches the limit, it is transparently restarted with a fresh PHP context.
+Other threads continue to serve requests during the restart, so there is no downtime.
+
+### Worker Mode
+
+For workers, `max_requests` is set per worker in the `worker` block:
+
+```caddyfile
+{
+	frankenphp {
+		worker {
+			file /path/to/your/worker.php
+			num 4
+			max_requests 500
+		}
+	}
+}
+```
+
+When a worker thread reaches the limit, the PHP worker script exits its loop
+and restarts automatically, similar to a graceful restart.
+
+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
@@ -786,5 +788,6 @@ func resetGlobals() {
 	workersByPath = nil
 	watcherIsEnabled = false
 	maxIdleTime = defaultMaxIdleTime
+	maxRequestsPerThread = 0
 	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,122 @@
+package frankenphp_test
+
+import (
+	"io"
+	"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. This is the module-mode equivalent of php-fpm's
+// pm.max_requests, cleaning up all ZTS state including leaky extensions.
+func TestModuleMaxRequests(t *testing.T) {
+	const maxRequests = 5
+	const totalRequests = 30
+
+	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?i=" + strings.Clone("0"))
+			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)
+		}
+	}, &testOptions{
+		nbParallelRequests: 1,
+		realServer:         true,
+		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?i=" + strings.Clone("0"))
+				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.Equal(t, totalRequests, successCount,
+			"all requests should succeed despite regular thread restarts")
+	}, &testOptions{
+		nbParallelRequests: 1,
+		realServer:         true,
+		initOpts: []frankenphp.Option{
+			frankenphp.WithNumThreads(4),
+			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?i=" + strings.Clone("0"))
+			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{
+		nbParallelRequests: 1,
+		realServer:         true,
+		initOpts:           []frankenphp.Option{frankenphp.WithNumThreads(2)},
+	})
+}