feat: background worker pools + multi-entrypoint

Seventh (final in the split) step of the split suggested in #2287.
Lifts the remaining constraints from the minimal path:

- Pools: named bg workers can now declare num > 1 (pool of threads
  per worker) and max_threads > 1. Each thread in the pool shares
  the same backgroundWorkerState, so set_vars / get_vars are scoped
  per-worker-name, not per-thread.

- Per-thread stop-pipe: the write fd moved from worker to handler.
  Each thread in a pool gets its own stop pipe, so drain() can wake
  them independently. Pools no longer overwrite one another's fd
  through the shared worker struct.

- Multi-entrypoint: multiple named bg workers in the same scope
  can share the same entrypoint file. Each gets its own registry
  from buildBackgroundWorkerLookups, so they inherit independent
  env/watch/failure-policy options. Drops the filename-uniqueness
  check for bg workers (it was already skipped via allowPathMatching,
  but this step lifts the last Caddyfile-level rejection).

- Caddyfile: `num > 1` and `max_threads > 1` on named background
  workers no longer error out. Catch-all semantics unchanged:
  max_threads caps lazy-started instance count.

## Tests

- TestBackgroundWorkerPool: num=3 pool, verifies all threads boot
  and share state through set_vars/get_vars.
- TestBackgroundWorkerMultiEntrypoint: two named bg workers sharing
  one entrypoint file resolve to distinct instances by name.

All previous bg worker tests still pass.

Author: nicolas-grekas

background_worker_pool_test.go

@@ -0,0 +1,98 @@
+package frankenphp_test
+
+import (
+	"errors"
+	"io"
+	"net/http/httptest"
+	"os"
+	"testing"
+
+	"github.com/dunglas/frankenphp"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestBackgroundWorkerPool declares a named bg worker with num=3 (pool
+// of three threads). All three threads should boot, share the same
+// registered backgroundWorkerState, and the reader can see the pool's
+// vars. This covers the lifted num>1 + max_threads>1 constraint.
+func TestBackgroundWorkerPool(t *testing.T) {
+	cwd, _ := os.Getwd()
+	testDataDir := cwd + "/testdata/"
+
+	require.NoError(t, frankenphp.Init(
+		frankenphp.WithWorkers("pool-worker", testDataDir+"background-worker-pool.php", 3,
+			frankenphp.WithWorkerBackground(),
+			frankenphp.WithWorkerMaxThreads(3)),
+		frankenphp.WithNumThreads(6),
+	))
+	t.Cleanup(frankenphp.Shutdown)
+
+	// Read the pool worker's vars via get_vars; all three threads share
+	// the same state so we don't need to target a specific one. ensure()
+	// waits for at least one pool thread's first set_vars so the eager
+	// start can't race the reader.
+	php := `<?php
+frankenphp_ensure_background_worker('pool-worker');
+$vars = frankenphp_get_vars('pool-worker');
+echo 'name=', $vars['name'] ?? 'MISSING', "\n";
+echo 'has-pid=', isset($vars['pid']) ? '1' : '0', "\n";
+`
+	tmp := testDataDir + "pool-reader.php"
+	require.NoError(t, os.WriteFile(tmp, []byte(php), 0644))
+	t.Cleanup(func() { _ = os.Remove(tmp) })
+
+	req := httptest.NewRequest("GET", "http://example.com/pool-reader.php", nil)
+	fr, err := frankenphp.NewRequestWithContext(req, frankenphp.WithRequestDocumentRoot(testDataDir, false))
+	require.NoError(t, err)
+
+	w := httptest.NewRecorder()
+	if err := frankenphp.ServeHTTP(w, fr); err != nil && !errors.As(err, &frankenphp.ErrRejected{}) {
+		t.Fatalf("serve: %v", err)
+	}
+	body, _ := io.ReadAll(w.Result().Body)
+	out := string(body)
+
+	assert.NotContains(t, out, "MISSING", "pool worker should have published its vars:\n"+out)
+	assert.Contains(t, out, "name=pool-worker")
+	assert.Contains(t, out, "has-pid=1")
+}
+
+// TestBackgroundWorkerMultiEntrypoint declares two named bg workers that
+// share the same entrypoint file. Each registry is independent, so ensure()
+// + get_vars resolve to the correct instance by name.
+func TestBackgroundWorkerMultiEntrypoint(t *testing.T) {
+	cwd, _ := os.Getwd()
+	testDataDir := cwd + "/testdata/"
+
+	require.NoError(t, frankenphp.Init(
+		frankenphp.WithWorkers("shared-a", testDataDir+"background-worker-named.php", 1,
+			frankenphp.WithWorkerBackground()),
+		frankenphp.WithWorkers("shared-b", testDataDir+"background-worker-named.php", 1,
+			frankenphp.WithWorkerBackground()),
+		frankenphp.WithNumThreads(5),
+	))
+	t.Cleanup(frankenphp.Shutdown)
+
+	read := func(name string) string {
+		php := `<?php
+frankenphp_ensure_background_worker(` + "'" + name + "'" + `);
+$vars = frankenphp_get_vars(` + "'" + name + "'" + `);
+echo $vars['FRANKENPHP_WORKER_NAME'] ?? 'MISSING';
+`
+		tmp := testDataDir + "multi-entry-reader-" + name + ".php"
+		require.NoError(t, os.WriteFile(tmp, []byte(php), 0644))
+		t.Cleanup(func() { _ = os.Remove(tmp) })
+
+		req := httptest.NewRequest("GET", "http://example.com/multi-entry-reader-"+name+".php", nil)
+		fr, err := frankenphp.NewRequestWithContext(req, frankenphp.WithRequestDocumentRoot(testDataDir, false))
+		require.NoError(t, err)
+		w := httptest.NewRecorder()
+		_ = frankenphp.ServeHTTP(w, fr)
+		body, _ := io.ReadAll(w.Result().Body)
+		return string(body)
+	}
+
+	assert.Equal(t, "shared-a", read("shared-a"), "shared-a name must resolve to its own worker")
+	assert.Equal(t, "shared-b", read("shared-b"), "shared-b name must resolve to its own worker")
+}

caddy/workerconfig.go

@@ -164,15 +164,10 @@ func unmarshalWorker(d *caddyfile.Dispenser) (workerConfig, error) {
 	}
 
 	if wc.Background {
-		if wc.Num > 1 {
-			return wc, d.Err(`"num" > 1 is not yet supported for background workers`)
-		}
-		// For named bg workers, max_threads is threads-per-worker (>1 not
-		// yet supported). For the catch-all (no name), it's the cap on
-		// lazy-started instance count, which is a legitimate user knob.
-		if wc.Name != "" && wc.MaxThreads > 1 {
-			return wc, d.Err(`"max_threads" > 1 is not yet supported for named background workers`)
-		}
+		// Named bg workers: num and max_threads mean "threads per worker"
+		// (pool size and pool cap). Catch-all bg workers: num is the pool
+		// size of the placeholder instance (usually 1), max_threads caps
+		// how many distinct names can be lazy-started.
 		if len(wc.MatchPath) != 0 {
 			return wc, d.Err(`"match" is not supported for background workers`)
 		}

testdata/background-worker-pool.php

@@ -0,0 +1,23 @@
+<?php
+
+// Long-lived bg worker: disable PHP max_execution_time so the 30s default
+// cannot interrupt the stream_select park. The C side calls
+// zend_unset_timeout() too, but the belt-and-suspenders here covers PHP
+// builds where that path does not fully disarm the timer.
+set_time_limit(0);
+
+// Pool worker: num > 1 means multiple threads share this worker name.
+// Each thread is a separate instance. We publish the thread's $_SERVER
+// identifying fields so the test can see both instances are live.
+frankenphp_set_vars([
+    'name' => $_SERVER['FRANKENPHP_WORKER_NAME'] ?? 'unknown',
+    'pid' => getmypid(),
+]);
+
+$stream = frankenphp_get_worker_handle();
+if ($stream !== null) {
+    $read = [$stream];
+    $write = null;
+    $except = null;
+    stream_select($read, $write, $except, null);
+}

threadbackgroundworker.go

@@ -67,6 +67,11 @@ type backgroundWorkerThread struct {
 	dummyContext           context.Context
 	isBootingScript        bool
 	failureCount           int
+
+	// stopFdWrite is the write end of THIS thread's stop pipe. Per-thread
+	// so pool workers (num > 1) can each be drained independently; the
+	// bg script uses the read end via frankenphp_get_worker_handle().
+	stopFdWrite atomic.Int32
 }
 
 func convertToBackgroundWorkerThread(thread *phpThread, worker *worker) {
@@ -97,9 +102,10 @@ func (handler *backgroundWorkerThread) context() context.Context {
 // drain is called by drainWorkerThreads (and thread.shutdown) right before
 // drainChan is closed. We close the stop-pipe's write end so the PHP worker
 // script, which is typically parked in stream_select on the read end, wakes
-// up and can finish its loop gracefully.
+// up and can finish its loop gracefully. Per-thread fd so pool workers
+// drain their threads independently.
 func (handler *backgroundWorkerThread) drain() {
-	if fd := handler.worker.backgroundStopFdWrite.Swap(-1); fd >= 0 {
+	if fd := handler.stopFdWrite.Swap(-1); fd >= 0 {
 		C.frankenphp_worker_close_fd(C.int(fd))
 	}
 }
@@ -162,7 +168,7 @@ func (handler *backgroundWorkerThread) setupScript() {
 
 	opts := append([]RequestOption(nil), handler.worker.requestOptions...)
 	C.frankenphp_set_worker_name(handler.thread.pinCString(strings.TrimPrefix(handler.worker.name, "m#")), C._Bool(true))
-	handler.worker.backgroundStopFdWrite.Store(int32(C.frankenphp_worker_get_stop_fd_write()))
+	handler.stopFdWrite.Store(int32(C.frankenphp_worker_get_stop_fd_write()))
 
 	fc, err := newDummyContext(
 		filepath.Base(handler.worker.fileName),
@@ -188,7 +194,7 @@ func (handler *backgroundWorkerThread) setupScript() {
 }
 
 func (handler *backgroundWorkerThread) afterScriptExecution(exitStatus int) {
-	handler.worker.backgroundStopFdWrite.Store(-1)
+	handler.stopFdWrite.Store(-1)
 	worker := handler.worker
 	handler.dummyFrankenPHPContext = nil
 	handler.dummyContext = nil

worker.go

@@ -39,7 +39,6 @@ type worker struct {
 	backgroundWorker       *backgroundWorkerState
 	backgroundRegistry     *backgroundWorkerRegistry
 	backgroundReserveOnce  sync.Once
-	backgroundStopFdWrite  atomic.Int32 // write end of the stop pipe, -1 if not set
 }
 
 var (
@@ -178,10 +177,10 @@ func newWorker(o workerOpt) (*worker, error) {
 		isBackgroundWorker:     o.isBackgroundWorker,
 	}
 
-	w.backgroundStopFdWrite.Store(-1)
 	// backgroundWorker state is reserved lazily via the registry at
 	// thread-setup time, not here; lazy-start callers set it directly
-	// and eager inits go through setupScript's sync.Once.
+	// and eager inits go through setupScript's sync.Once. The stop-pipe
+	// write fd is per-thread (handler field), not per-worker.
 
 	w.configureMercure(&o)