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/background-worker.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/background-worker-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/background-worker.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/background-worker-named.php", 0,
+			frankenphp.WithWorkerBackground(),
+			frankenphp.WithWorkerMaxThreads(8),
+			frankenphp.WithWorkerEnv(map[string]string{"BG_SENTINEL_DIR": tmp}),
+		),
+		frankenphp.WithNumThreads(8),
+	)
+
+	body := serveBody(t, testDataDir, "background-worker-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/background-worker-named.php", 0,
+			frankenphp.WithWorkerBackground(),
+		),
+		frankenphp.WithNumThreads(2),
+	)
+
+	body := serveBody(t, testDataDir, "background-worker-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/background-worker-named.php", 0,
+			frankenphp.WithWorkerBackground(),
+		),
+		frankenphp.WithNumThreads(2),
+	)
+
+	body := serveBody(t, testDataDir, "background-worker-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/background-worker-named.php", 0,
+			frankenphp.WithWorkerBackground(),
+		),
+		frankenphp.WithNumThreads(2),
+	)
+
+	body := serveBody(t, testDataDir, "background-worker-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/background-worker-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")
+}