feat: background worker pools + multi-entrypoint

Lifts the remaining constraints on background workers:

- Pools: named bg workers can now declare num > 1 (pool of threads
  per worker) and max_threads > 1. The Caddyfile-level rejections
  in unmarshalWorker are dropped.

- 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. Drops the filename-uniqueness
  rejection in newWorker (it was already skipped via
  allowPathMatching, this lifts the last Caddyfile-level path check
  that prevented two named bg workers pointing at the same fixture).

Tests:

- TestBackgroundWorkerPool: declares num=3, asserts 3 distinct
  sentinel files appear (each thread tempnam()'s a unique file).
- TestBackgroundWorkerMultiEntrypoint: two named bg workers share
  one entrypoint file; both Init successfully and produce sentinels.

Author: nicolas-grekas

background_worker_pool_test.go

@@ -0,0 +1,81 @@
+package frankenphp_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/dunglas/frankenphp"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// countSentinels returns the number of files under dir.
+func countSentinels(t *testing.T, dir string) int {
+	t.Helper()
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		t.Fatalf("read sentinel dir %q: %v", dir, err)
+	}
+	return len(entries)
+}
+
+// TestBackgroundWorkerPool declares a named bg worker with num=3 (pool of
+// three threads). Each thread touches a unique sentinel under
+// BG_SENTINEL_DIR via tempnam(), so the test can assert that all three
+// pool threads booted independently. Covers the lifted num>1 +
+// max_threads>1 constraints and the per-thread stop pipe.
+func TestBackgroundWorkerPool(t *testing.T) {
+	cwd, _ := os.Getwd()
+	testDataDir := cwd + "/testdata/"
+
+	tmp := t.TempDir()
+
+	require.NoError(t, frankenphp.Init(
+		frankenphp.WithWorkers("pool-worker", testDataDir+"background-worker-pool.php", 3,
+			frankenphp.WithWorkerBackground(),
+			frankenphp.WithWorkerMaxThreads(3),
+			frankenphp.WithWorkerEnv(map[string]string{"BG_SENTINEL_DIR": tmp}),
+		),
+		frankenphp.WithNumThreads(6),
+	))
+	t.Cleanup(frankenphp.Shutdown)
+
+	require.Eventually(t, func() bool {
+		return countSentinels(t, tmp) == 3
+	}, 5*time.Second, 25*time.Millisecond,
+		"expected 3 distinct pool sentinels, got %d", countSentinels(t, tmp))
+}
+
+// TestBackgroundWorkerMultiEntrypoint declares two named bg workers that
+// share the same entrypoint file. Each gets its own registry entry, so
+// both Init successfully (no filename-collision rejection) and both
+// produce sentinels.
+func TestBackgroundWorkerMultiEntrypoint(t *testing.T) {
+	cwd, _ := os.Getwd()
+	testDataDir := cwd + "/testdata/"
+
+	tmp := t.TempDir()
+
+	require.NoError(t, frankenphp.Init(
+		frankenphp.WithWorkers("shared-a", testDataDir+"background-worker-named.php", 1,
+			frankenphp.WithWorkerBackground(),
+			frankenphp.WithWorkerEnv(map[string]string{"BG_SENTINEL_DIR": tmp}),
+		),
+		frankenphp.WithWorkers("shared-b", testDataDir+"background-worker-named.php", 1,
+			frankenphp.WithWorkerBackground(),
+			frankenphp.WithWorkerEnv(map[string]string{"BG_SENTINEL_DIR": tmp}),
+		),
+		frankenphp.WithNumThreads(5),
+	))
+	t.Cleanup(frankenphp.Shutdown)
+
+	for _, name := range []string{"shared-a", "shared-b"} {
+		assert.Eventually(t, func() bool {
+			_, err := os.Stat(filepath.Join(tmp, name))
+			return err == nil
+		}, 5*time.Second, 25*time.Millisecond,
+			"shared bg worker %q did not touch its sentinel", name)
+	}
+}

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 runs in its own ZTS context, but getmypid() returns the
+// shared process pid. We use tempnam() to atomically create a unique
+// file per thread so the test can count N distinct booted threads.
+if (!empty($_SERVER['BG_SENTINEL_DIR'])) {
+    @tempnam($_SERVER['BG_SENTINEL_DIR'], 'pool');
+}
+
+$stream = frankenphp_get_worker_handle();
+if ($stream !== null) {
+    $read = [$stream];
+    $write = null;
+    $except = null;
+    stream_select($read, $write, $except, null);
+}

threadbackgroundworker.go

@@ -8,6 +8,7 @@ import (
 	"log/slog"
 	"path/filepath"
 	"strings"
+	"sync/atomic"
 	"time"
 
 	"github.com/dunglas/frankenphp/internal/state"
@@ -26,6 +27,11 @@ type backgroundWorkerThread struct {
 	dummyFrankenPHPContext *frankenPHPContext
 	dummyContext           context.Context
 	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) {
@@ -34,6 +40,7 @@ func convertToBackgroundWorkerThread(thread *phpThread, worker *worker) {
 		thread: thread,
 		worker: worker,
 	}
+	handler.stopFdWrite.Store(-1)
 	thread.setHandler(handler)
 	worker.attachThread(thread)
 }
@@ -56,9 +63,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))
 	}
 }
@@ -103,7 +111,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),
@@ -128,7 +136,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

@@ -36,7 +36,6 @@ type worker struct {
 	isBackgroundWorker     bool
 	backgroundScope        BackgroundScope
 	backgroundRegistry     *backgroundWorkerRegistry
-	backgroundStopFdWrite  atomic.Int32 // write end of the stop pipe, -1 if not set
 }
 
 var (
@@ -147,13 +146,16 @@ func newWorker(o workerOpt) (*worker, error) {
 	// they don't handle HTTP requests.
 	allowPathMatching := !strings.HasPrefix(o.name, "m#") && !o.isBackgroundWorker
 
-	if w := workersByPath[absFileName]; w != nil && allowPathMatching {
-		return w, fmt.Errorf("two workers cannot have the same filename: %q", absFileName)
-	}
-	// Background workers are resolved through per-scope lookups, not the
-	// global workersByName map; the same user-facing name can appear in
-	// multiple php_server scopes without collision.
+	// Background workers are matched only by name, never by path. Multiple
+	// named bg workers can share an entrypoint file; uniqueness is enforced
+	// per-scope via backgroundLookups, not at the global path level.
 	if !o.isBackgroundWorker {
+		if w := workersByPath[absFileName]; w != nil && allowPathMatching {
+			return w, fmt.Errorf("two workers cannot have the same filename: %q", absFileName)
+		}
+		// Background workers are resolved through per-scope lookups, not the
+		// global workersByName map; the same user-facing name can appear in
+		// multiple php_server scopes without collision.
 		if w := workersByName[o.name]; w != nil {
 			return w, fmt.Errorf("two workers cannot have the same name: %q", o.name)
 		}
@@ -180,7 +182,8 @@ func newWorker(o workerOpt) (*worker, error) {
 		backgroundScope:        o.backgroundScope,
 	}
 
-	w.backgroundStopFdWrite.Store(-1)
+	// The stop-pipe write fd is per-thread (handler field), not per-worker,
+	// so each thread in a num > 1 pool can be drained independently.
 
 	w.configureMercure(&o)