feat: background workers (config + ensure)

Adds background workers — long-lived non-HTTP PHP scripts that share
the FrankenPHP runtime with HTTP workers but stay outside the request
cycle. Implements:

- WithWorkerBackground option / Caddyfile `worker { background }`
  declares a worker as a bg worker. $_SERVER['FRANKENPHP_WORKER']
  carries the user-facing worker name, $_SERVER['FRANKENPHP_WORKER_BACKGROUND']
  is true for bg workers so scripts can branch without checking every
  function independently.

- frankenphp_ensure_background_worker(string|array $name, ?float $timeout)
  lazy-starts a named bg worker (num=0 declarations stay parked until
  ensure() is called) or matches a catch-all declaration to spawn a
  named instance. Accepts an array of names sharing one deadline.
  Two-mode: fail-fast in HTTP-worker bootstrap so a broken dependency
  surfaces at boot; tolerant inside requests so the restart cycle can
  recover from transient boot failures.

- Per-php_server scope isolation: each php_server block gets its own
  Scope (opaque uint64). Workers in distinct scopes can share a name
  without colliding. The Caddy module resolves a human-friendly label
  via cascade (route host matcher -> user-set Caddy server name ->
  first listener address) and registers it via SetScopeLabel so future
  metric/log emitters can render server="api.example.com".

- Catch-all dispatch: a name-less bg worker declaration matches any
  ensure() name at runtime. max_threads on a catch-all caps how many
  distinct lazy-started instance names it can host (default 16).

- bg-worker bootstrap routes the runtime name through the CGI pipeline
  so $_SERVER['FRANKENPHP_WORKER'] reflects the user-facing name on
  every request, not just bg-worker boot.

- Bg workers expose a stop pipe (frankenphp_get_worker_handle) so PHP
  scripts can park on stream_select and exit gracefully when
  FrankenPHP drains.

- max_consecutive_failures cap fails Init fast (HTTP-worker mode) or
  shuts the bg-worker thread down cleanly, with a deterministic abort
  message instead of a generic ensure() timeout.

Tests cover: Caddyfile + Go-API declarations, ensure() lazy-start,
catch-all dispatch + cap, batch ensure with shared deadline, error
paths (undeclared name, boot failure metadata, type-validation), per-
php_server scope isolation including same-named workers in distinct
scopes.

Author: nicolas-grekas

bgworker.go

@@ -0,0 +1,86 @@
+package frankenphp_test
+
+import (
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/dunglas/frankenphp"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestBackgroundWorkerLifecycle boots a background worker that touches a
+// sentinel file then parks on the stop pipe. It proves the bg worker runs
+// (sentinel appears) and that Shutdown returns within a reasonable time.
+func TestBackgroundWorkerLifecycle(t *testing.T) {
+	tmp := t.TempDir()
+	sentinel := filepath.Join(tmp, "bg-lifecycle.sentinel")
+
+	require.NoError(t, frankenphp.Init(
+		frankenphp.WithWorkers("bg-lifecycle", "testdata/bgworker/basic.php", 1,
+			frankenphp.WithWorkerBackground(),
+			frankenphp.WithWorkerEnv(map[string]string{"BG_SENTINEL": sentinel}),
+		),
+		frankenphp.WithNumThreads(2),
+	))
+	// Note: this test asserts on Shutdown timing, so it manages Shutdown
+	// itself instead of using setupFrankenPHP's t.Cleanup hook.
+
+	requireFileEventually(t, sentinel, "background worker did not touch sentinel")
+
+	done := make(chan struct{})
+	go func() {
+		frankenphp.Shutdown()
+		close(done)
+	}()
+
+	select {
+	case <-done:
+	case <-time.After(10 * time.Second):
+		t.Fatalf("Shutdown did not return within 10s")
+	}
+}
+
+// TestBackgroundWorkerCrashRestarts boots a worker that exit(1)s on its
+// first run and touches a "restarted" sentinel on its second run. The
+// sentinel proves the crash-restart loop fired.
+func TestBackgroundWorkerCrashRestarts(t *testing.T) {
+	tmp := t.TempDir()
+	crashMarker := filepath.Join(tmp, "bg-crash.marker")
+	restarted := filepath.Join(tmp, "bg-crash.restarted")
+
+	setupFrankenPHP(t,
+		frankenphp.WithWorkers("bg-crash", "testdata/bgworker/crash.php", 1,
+			frankenphp.WithWorkerBackground(),
+			frankenphp.WithWorkerEnv(map[string]string{
+				"BG_CRASH_MARKER":       crashMarker,
+				"BG_RESTARTED_SENTINEL": restarted,
+			}),
+		),
+		frankenphp.WithNumThreads(2),
+	)
+
+	requireFileEventually(t, restarted, "background worker did not restart after crash")
+}
+
+// TestBackgroundWorkerWithoutHTTP confirms that a request to a script
+// unrelated to the bg worker still works: the bg worker doesn't intercept
+// HTTP traffic.
+func TestBackgroundWorkerWithoutHTTP(t *testing.T) {
+	tmp := t.TempDir()
+	sentinel := filepath.Join(tmp, "bg-nohttp.sentinel")
+
+	testDataDir := setupFrankenPHP(t,
+		frankenphp.WithWorkers("bg-nohttp", "testdata/bgworker/basic.php", 1,
+			frankenphp.WithWorkerBackground(),
+			frankenphp.WithWorkerEnv(map[string]string{"BG_SENTINEL": sentinel}),
+		),
+		frankenphp.WithNumThreads(2),
+	)
+
+	requireFileEventually(t, sentinel, "background worker did not touch sentinel")
+
+	body := serveBody(t, testDataDir, "index.php")
+	assert.NotEmpty(t, body, "expected non-empty body from index.php")
+}

bgworker_test.go

@@ -0,0 +1,107 @@
+package frankenphp_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/dunglas/frankenphp"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestEnsureBackgroundWorkerBatch declares a single catch-all bg worker
+// and ensures three distinct names from a single ensure() call. Each
+// catch-all instance touches a per-name sentinel; the test asserts that
+// all three appear, proving the array form started one worker per name.
+func TestEnsureBackgroundWorkerBatch(t *testing.T) {
+	tmp := t.TempDir()
+	testDataDir := setupFrankenPHP(t,
+		frankenphp.WithWorkers("", "testdata/bgworker/named.php", 0,
+			frankenphp.WithWorkerBackground(),
+			frankenphp.WithWorkerMaxThreads(8),
+			frankenphp.WithWorkerEnv(map[string]string{"BG_SENTINEL_DIR": tmp}),
+		),
+		frankenphp.WithNumThreads(8),
+	)
+
+	body := serveBody(t, testDataDir, "bgworker/batch-ensure.php")
+	assert.Contains(t, body, "ok", "batch ensure script should echo ok, got: %q", body)
+
+	for _, name := range []string{"batch-a", "batch-b", "batch-c"} {
+		requireFileEventually(t, filepath.Join(tmp, name),
+			"catch-all instance %q should have written its sentinel", name)
+	}
+}
+
+// TestEnsureBackgroundWorkerBatchEmpty exercises the C-side validation
+// that an empty array raises a ValueError before any worker is started.
+// The fixture catches the throwable and echoes its class.
+func TestEnsureBackgroundWorkerBatchEmpty(t *testing.T) {
+	testDataDir := setupFrankenPHP(t,
+		frankenphp.WithWorkers("", "testdata/bgworker/named.php", 0,
+			frankenphp.WithWorkerBackground(),
+		),
+		frankenphp.WithNumThreads(2),
+	)
+
+	body := serveBody(t, testDataDir, "bgworker/batch-errors.php?mode=empty")
+	assert.Contains(t, body, "ValueError", "empty array should raise ValueError, got: %q", body)
+	assert.Contains(t, body, "must not be empty")
+}
+
+// TestEnsureBackgroundWorkerBatchNonString verifies a non-string element
+// raises a TypeError (PHP's standard for argument-type mismatches inside
+// our parsed array).
+func TestEnsureBackgroundWorkerBatchNonString(t *testing.T) {
+	testDataDir := setupFrankenPHP(t,
+		frankenphp.WithWorkers("", "testdata/bgworker/named.php", 0,
+			frankenphp.WithWorkerBackground(),
+		),
+		frankenphp.WithNumThreads(2),
+	)
+
+	body := serveBody(t, testDataDir, "bgworker/batch-errors.php?mode=nonstring")
+	assert.Contains(t, body, "TypeError", "non-string element should raise TypeError, got: %q", body)
+}
+
+// TestEnsureBackgroundWorkerBatchDuplicate verifies that duplicate names
+// in the same batch are rejected as a ValueError, matching the e17577e
+// reference behavior (no silent dedup).
+func TestEnsureBackgroundWorkerBatchDuplicate(t *testing.T) {
+	testDataDir := setupFrankenPHP(t,
+		frankenphp.WithWorkers("", "testdata/bgworker/named.php", 0,
+			frankenphp.WithWorkerBackground(),
+		),
+		frankenphp.WithNumThreads(2),
+	)
+
+	body := serveBody(t, testDataDir, "bgworker/batch-errors.php?mode=duplicate")
+	assert.Contains(t, body, "ValueError", "duplicate name should raise ValueError, got: %q", body)
+	assert.Contains(t, body, "duplicate")
+}
+
+// TestBackgroundWorkerBgFlag asserts that a bg worker script sees
+// $_SERVER['FRANKENPHP_WORKER_BACKGROUND'] === true. The fixture writes
+// var_export() of the value to a sentinel so the test can read the exact
+// PHP-level representation.
+func TestBackgroundWorkerBgFlag(t *testing.T) {
+	tmp := t.TempDir()
+	sentinel := filepath.Join(tmp, "bg-flag.sentinel")
+
+	setupFrankenPHP(t,
+		frankenphp.WithWorkers("bg-flag", "testdata/bgworker/bg-flag.php", 1,
+			frankenphp.WithWorkerBackground(),
+			frankenphp.WithWorkerEnv(map[string]string{"BG_SENTINEL": sentinel}),
+		),
+		frankenphp.WithNumThreads(2),
+	)
+
+	requireFileEventually(t, sentinel,
+		"bg worker should have written the FRANKENPHP_WORKER_BACKGROUND sentinel")
+
+	contents, err := os.ReadFile(sentinel)
+	require.NoError(t, err)
+	assert.Equal(t, "true", string(contents),
+		"$_SERVER['FRANKENPHP_WORKER_BACKGROUND'] should be the bool true")
+}

bgworkerbatch_test.go

@@ -0,0 +1,188 @@
+package frankenphp
+
+import (
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestEnsureBackgroundWorkerNamedLazy declares a num=0 named worker, then
+// calls ensure() to lazy-start it. The fixture writes a sentinel named
+// after FRANKENPHP_WORKER so we can confirm the right instance ran.
+func TestEnsureBackgroundWorkerNamedLazy(t *testing.T) {
+	tmp := t.TempDir()
+	setupBgWorker(t,
+		WithWorkers("bg-lazy", "testdata/bgworker/named.php", 0,
+			WithWorkerBackground(),
+			WithWorkerEnv(map[string]string{"BG_SENTINEL_DIR": tmp}),
+		),
+		WithNumThreads(2),
+	)
+
+	// num=0 means no eager start: the sentinel should not exist yet.
+	require.NoFileExists(t, filepath.Join(tmp, "bg-lazy"), "lazy worker should not have started yet")
+
+	require.NoError(t, ensureBackgroundWorker(nil, "bg-lazy", 5*time.Second))
+	requireSentinelEventually(t, filepath.Join(tmp, "bg-lazy"),
+		"ensure() should have lazy-started the named bg worker")
+}
+
+// TestEnsureBackgroundWorkerCatchAll declares a single catch-all (no name)
+// and invokes ensure() with two distinct names. Each name should spawn an
+// independent instance from the same entrypoint and write its own sentinel.
+func TestEnsureBackgroundWorkerCatchAll(t *testing.T) {
+	tmp := t.TempDir()
+	setupBgWorker(t,
+		// Name-less bg worker = catch-all.
+		WithWorkers("", "testdata/bgworker/named.php", 0,
+			WithWorkerBackground(),
+			WithWorkerEnv(map[string]string{"BG_SENTINEL_DIR": tmp}),
+		),
+		WithNumThreads(4),
+	)
+
+	for _, name := range []string{"job-a", "job-b"} {
+		require.NoError(t, ensureBackgroundWorker(nil, name, 5*time.Second), "ensure(%s)", name)
+	}
+
+	for _, name := range []string{"job-a", "job-b"} {
+		requireSentinelEventually(t, filepath.Join(tmp, name),
+			"catch-all instance %q should have written its sentinel", name)
+	}
+}
+
+// TestEnsureBackgroundWorkerCatchAllCap exercises max_threads on the
+// catch-all: third distinct name beyond the cap should error.
+func TestEnsureBackgroundWorkerCatchAllCap(t *testing.T) {
+	tmp := t.TempDir()
+	setupBgWorker(t,
+		WithWorkers("", "testdata/bgworker/named.php", 0,
+			WithWorkerBackground(),
+			WithWorkerMaxThreads(2),
+			WithWorkerEnv(map[string]string{"BG_SENTINEL_DIR": tmp}),
+		),
+		WithNumThreads(4),
+	)
+
+	require.NoError(t, ensureBackgroundWorker(nil, "cap-a", 5*time.Second))
+	require.NoError(t, ensureBackgroundWorker(nil, "cap-b", 5*time.Second))
+
+	require.ErrorContains(t,
+		ensureBackgroundWorker(nil, "cap-c", 5*time.Second),
+		"limit of 2 reached",
+		"third ensure must hit the catch-all cap")
+}
+
+// TestEnsureBackgroundWorkerUndeclared confirms ensure() on an undeclared
+// name with no catch-all returns the configuration error.
+func TestEnsureBackgroundWorkerUndeclared(t *testing.T) {
+	setupBgWorker(t,
+		WithWorkers("bg-known", "testdata/bgworker/named.php", 0,
+			WithWorkerBackground(),
+		),
+		WithNumThreads(2),
+	)
+
+	require.ErrorContains(t,
+		ensureBackgroundWorker(nil, "other-name", 5*time.Second),
+		"no background worker configured for name")
+}
+
+// TestEnsureBackgroundWorkerConcurrent confirms the doc claim that ensure()
+// is safe to call concurrently: 16 goroutines hitting the same lazy-named
+// declaration produce exactly one spawned thread. Without serialising the
+// lazy-start gate (bgLazyStartMu), the second caller could observe the
+// flag before the first caller has completed thread reservation, leaving
+// the worker in an inconsistent state.
+func TestEnsureBackgroundWorkerConcurrent(t *testing.T) {
+	setupBgWorker(t,
+		WithWorkers("bg-concurrent", "testdata/bgworker/named.php", 0,
+			WithWorkerBackground(),
+		),
+		WithNumThreads(8),
+	)
+
+	const goroutines = 16
+	var wg sync.WaitGroup
+	wg.Add(goroutines)
+	errs := make([]error, goroutines)
+	start := make(chan struct{})
+	for i := 0; i < goroutines; i++ {
+		go func(idx int) {
+			defer wg.Done()
+			<-start
+			errs[idx] = ensureBackgroundWorker(nil, "bg-concurrent", 5*time.Second)
+		}(i)
+	}
+	close(start)
+	wg.Wait()
+
+	for i, err := range errs {
+		require.NoError(t, err, "goroutine %d", i)
+	}
+
+	// The lazy-named declaration should resolve to its single *worker,
+	// and exactly one thread should have been spawned by the lazy-start
+	// path despite the 16 concurrent ensure() callers.
+	lookup := backgroundLookups[0]
+	require.NotNil(t, lookup)
+	w := lookup.byName["bg-concurrent"]
+	require.NotNil(t, w)
+	assert.Equal(t, 1, w.countThreads(), "exactly one worker thread expected")
+}
+
+// TestEnsureBackgroundWorkerTimeout proves ensure() blocks until either
+// the worker hits its readiness boundary (frankenphp_get_worker_handle())
+// or the timeout expires. The fixture sleep()s without ever calling the
+// readiness function, so the second branch must fire.
+func TestEnsureBackgroundWorkerTimeout(t *testing.T) {
+	setupBgWorker(t,
+		WithWorkers("bg-no-handle", "testdata/bgworker/no-handle.php", 0,
+			WithWorkerBackground(),
+		),
+		WithNumThreads(2),
+	)
+
+	start := time.Now()
+	err := ensureBackgroundWorker(nil, "bg-no-handle", 1*time.Second)
+	deadline := start.Add(1 * time.Second)
+
+	require.ErrorContains(t, err,
+		"did not call frankenphp_get_worker_handle()",
+		"ensure() must time out at the readiness boundary")
+	// Lower bound: timer must actually have run; allow a little slop for
+	// timer scheduling.
+	assert.GreaterOrEqual(t, time.Since(start), 900*time.Millisecond, "ensure() must wait the full timeout")
+	// Upper bound: ensure() returned close to the deadline (didn't hang).
+	assert.WithinDuration(t, deadline, time.Now(), 4*time.Second, "ensure() must return within a small slack window after the timeout")
+}
+
+// TestEnsureBackgroundWorkerBootFailure declares a worker whose entrypoint
+// throws on its very first line. ensure() should surface the boot crash
+// metadata (entrypoint, exit status, attempt count) instead of just
+// reporting a generic timeout. We use a max_consecutive_failures cap so
+// the worker stops respawning and the abort path fires deterministically.
+func TestEnsureBackgroundWorkerBootFailure(t *testing.T) {
+	setupBgWorker(t,
+		WithWorkers("bg-boot-fail", "testdata/bgworker/boot-fail.php", 0,
+			WithWorkerBackground(),
+			WithWorkerMaxFailures(2),
+		),
+		WithNumThreads(2),
+	)
+
+	err := ensureBackgroundWorker(nil, "bg-boot-fail", 5*time.Second)
+	require.Error(t, err, "ensure() must surface the boot failure")
+	msg := err.Error()
+	// One of two paths: either the abort fired (cap reached) and the error
+	// mentions max_consecutive_failures, or the timeout fired with the
+	// bootFailureInfo attached so the message mentions exit status.
+	assert.True(t,
+		strings.Contains(msg, "exit status") || strings.Contains(msg, "max_consecutive_failures") || strings.Contains(msg, "failed to start"),
+		"ensure() error must reflect the boot crash, got: %s", msg)
+}