feat: batch ensure + FRANKENPHP_WORKER_BACKGROUND server flag

Eighth step on top of #2287's split. User-facing polish on the ensure
API plus a small $_SERVER flag, both landing together because they are
small and closely related to the worker-handling surface.

- frankenphp_ensure_background_worker now accepts string|array. The
  array form shares one deadline across all names and preserves the
  same mode semantics (fail-fast in HTTP-worker bootstrap, tolerant
  everywhere else). Empty arrays and non-string elements raise clear
  ValueError / TypeError instead of silent no-ops or cryptic
  failures.

- $_SERVER['FRANKENPHP_WORKER_BACKGROUND'] = true in background worker
  scripts, alongside the existing FRANKENPHP_WORKER_NAME and argv/argc
  wiring. Gives scripts a single-key branch for "am I a bg worker?"
  without checking each function independently.

## Tests

- TestEnsureBackgroundWorkerBatch: three workers ensured in one call,
  each publishing its own name, all read back after the batch
  returns.
- TestEnsureBackgroundWorkerBatchEmpty: [] rejected with ValueError.
- TestEnsureBackgroundWorkerBatchNonString: ['a', 42] rejected with
  TypeError before any worker starts.
- TestBackgroundWorkerServerFlag: bg worker sees
  FRANKENPHP_WORKER_BACKGROUND=true in $_SERVER.

## Deferred

- CLI-mode function hiding was in the sidekicks draft but turned out
  to be dead code (the frankenphp PHP module isn't loaded in CLI, so
  the functions don't exist there either).
- C-side per-request get_vars cache: step 9 (needs benchmarks).
- Docs: step 10 (will cover the final API including batch ensure).

Author: nicolas-grekas

background_worker.go

@@ -380,9 +380,10 @@ func isBootstrapEnsure(thread *phpThread) bool {
 	return ok && handler.isBootingScript
 }
 
-// go_frankenphp_ensure_background_worker declares a dependency on a
-// background worker by name. Lazy-starts it if not already running, then
-// blocks until it has called set_vars (ready state) or the timeout expires.
+// go_frankenphp_ensure_background_worker declares a dependency on one or
+// more background workers by name. Each named worker is lazy-started if
+// not already running; the call blocks until every one has reached ready
+// (set_vars called at least once) or the shared deadline expires.
 //
 // Bootstrap mode (HTTP worker before frankenphp_handle_request): fail-fast.
 // Any boot failure throws immediately with captured details, without
@@ -394,61 +395,78 @@ func isBootstrapEnsure(thread *phpThread) bool {
 // cycle recover from transient boot failures.
 //
 //export go_frankenphp_ensure_background_worker
-func go_frankenphp_ensure_background_worker(threadIndex C.uintptr_t, name *C.char, nameLen C.size_t, timeoutMs C.int) *C.char {
+func go_frankenphp_ensure_background_worker(threadIndex C.uintptr_t, names **C.char, nameLens *C.size_t, nameCount C.int, timeoutMs C.int) *C.char {
 	thread := phpThreads[threadIndex]
 	lookup := getLookup(thread)
 	if lookup == nil {
 		return C.CString("no background worker configured")
 	}
 
-	goName := C.GoStringN(name, C.int(nameLen))
+	n := int(nameCount)
+	nameSlice := unsafe.Slice(names, n)
+	nameLenSlice := unsafe.Slice(nameLens, n)
 	bootstrap := isBootstrapEnsure(thread)
-	if err := startBackgroundWorker(thread, goName); err != nil {
-		return C.CString(err.Error())
-	}
-	registry := lookup.Resolve(goName)
-	if registry == nil {
-		return C.CString("background worker not found: " + goName)
-	}
-	registry.mu.Lock()
-	sk := registry.workers[goName]
-	registry.mu.Unlock()
-	if sk == nil {
-		return C.CString("background worker not found: " + goName)
+
+	// Start each named worker first. Reserve their states so a shared
+	// deadline applies across the whole group (the caller gets one
+	// timeout value, not one per worker).
+	sks := make([]*backgroundWorkerState, n)
+	goNames := make([]string, n)
+	for i := 0; i < n; i++ {
+		goNames[i] = C.GoStringN(nameSlice[i], C.int(nameLenSlice[i]))
+		if err := startBackgroundWorker(thread, goNames[i]); err != nil {
+			return C.CString(err.Error())
+		}
+		registry := lookup.Resolve(goNames[i])
+		if registry == nil {
+			return C.CString("background worker not found: " + goNames[i])
+		}
+		registry.mu.Lock()
+		sks[i] = registry.workers[goNames[i]]
+		registry.mu.Unlock()
+		if sks[i] == nil {
+			return C.CString("background worker not found: " + goNames[i])
+		}
 	}
 
 	deadline := time.After(time.Duration(timeoutMs) * time.Millisecond)
 	if bootstrap {
 		ticker := time.NewTicker(50 * time.Millisecond)
 		defer ticker.Stop()
-		for {
-			select {
-			case <-sk.ready:
-				return nil
-			case <-sk.aborted:
-				return C.CString(sk.abortErr)
-			case <-deadline:
-				return C.CString(formatBackgroundWorkerTimeoutError(goName, sk))
-			case <-globalCtx.Done():
-				return C.CString("frankenphp is shutting down")
-			case <-ticker.C:
-				if sk.bootFailure.Load() != nil {
-					return C.CString(formatBackgroundWorkerTimeoutError(goName, sk))
+		for i, sk := range sks {
+		wait:
+			for {
+				select {
+				case <-sk.ready:
+					break wait
+				case <-sk.aborted:
+					return C.CString(sk.abortErr)
+				case <-deadline:
+					return C.CString(formatBackgroundWorkerTimeoutError(goNames[i], sk))
+				case <-globalCtx.Done():
+					return C.CString("frankenphp is shutting down")
+				case <-ticker.C:
+					if sk.bootFailure.Load() != nil {
+						return C.CString(formatBackgroundWorkerTimeoutError(goNames[i], sk))
+					}
 				}
 			}
 		}
+		return nil
 	}
 
-	select {
-	case <-sk.ready:
-		return nil
-	case <-sk.aborted:
-		return C.CString(sk.abortErr)
-	case <-deadline:
-		return C.CString(formatBackgroundWorkerTimeoutError(goName, sk))
-	case <-globalCtx.Done():
-		return C.CString("frankenphp is shutting down")
+	for i, sk := range sks {
+		select {
+		case <-sk.ready:
+		case <-sk.aborted:
+			return C.CString(sk.abortErr)
+		case <-deadline:
+			return C.CString(formatBackgroundWorkerTimeoutError(goNames[i], sk))
+		case <-globalCtx.Done():
+			return C.CString("frankenphp is shutting down")
+		}
 	}
+	return nil
 }
 
 func formatBackgroundWorkerTimeoutError(name string, sk *backgroundWorkerState) string {

background_worker_batch_test.go

@@ -0,0 +1,154 @@
+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"
+)
+
+// TestEnsureBackgroundWorkerBatch ensures multiple workers in one call,
+// each publishing its own identity. Verifies the batch path (array arg)
+// shares one deadline across all workers.
+func TestEnsureBackgroundWorkerBatch(t *testing.T) {
+	cwd, _ := os.Getwd()
+	testDataDir := cwd + "/testdata/"
+
+	require.NoError(t, frankenphp.Init(
+		frankenphp.WithWorkers("worker-a", testDataDir+"background-worker-named.php", 0,
+			frankenphp.WithWorkerBackground()),
+		frankenphp.WithWorkers("worker-b", testDataDir+"background-worker-named.php", 0,
+			frankenphp.WithWorkerBackground()),
+		frankenphp.WithWorkers("worker-c", testDataDir+"background-worker-named.php", 0,
+			frankenphp.WithWorkerBackground()),
+		frankenphp.WithNumThreads(6),
+	))
+	t.Cleanup(frankenphp.Shutdown)
+
+	req := httptest.NewRequest("GET", "http://example.com/background-worker-batch-ensure.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", "batch ensure should have started and published all workers:\n"+out)
+	assert.Contains(t, out, "worker-a=worker-a")
+	assert.Contains(t, out, "worker-b=worker-b")
+	assert.Contains(t, out, "worker-c=worker-c")
+}
+
+// TestEnsureBackgroundWorkerBatchEmpty verifies that an empty array is
+// rejected with a clear error rather than silently succeeding.
+func TestEnsureBackgroundWorkerBatchEmpty(t *testing.T) {
+	cwd, _ := os.Getwd()
+	testDataDir := cwd + "/testdata/"
+
+	require.NoError(t, frankenphp.Init(
+		frankenphp.WithWorkers("bg", testDataDir+"background-worker-named.php", 0,
+			frankenphp.WithWorkerBackground()),
+		frankenphp.WithNumThreads(3),
+	))
+	t.Cleanup(frankenphp.Shutdown)
+
+	php := `<?php
+try {
+    frankenphp_ensure_background_worker([], 1.0);
+    echo "FAIL no error";
+} catch (ValueError $e) {
+    echo "OK ", $e->getMessage();
+}`
+	tmp := testDataDir + "bg-batch-empty.php"
+	require.NoError(t, os.WriteFile(tmp, []byte(php), 0644))
+	t.Cleanup(func() { _ = os.Remove(tmp) })
+
+	req := httptest.NewRequest("GET", "http://example.com/bg-batch-empty.php", nil)
+	fr, _ := frankenphp.NewRequestWithContext(req, frankenphp.WithRequestDocumentRoot(testDataDir, false))
+	w := httptest.NewRecorder()
+	_ = frankenphp.ServeHTTP(w, fr)
+	body, _ := io.ReadAll(w.Result().Body)
+	assert.Contains(t, string(body), "OK ")
+	assert.Contains(t, string(body), "must not be empty")
+	assert.NotContains(t, string(body), "FAIL")
+}
+
+// TestEnsureBackgroundWorkerBatchNonString verifies array-entry type
+// validation: non-string elements produce a TypeError.
+func TestEnsureBackgroundWorkerBatchNonString(t *testing.T) {
+	cwd, _ := os.Getwd()
+	testDataDir := cwd + "/testdata/"
+
+	require.NoError(t, frankenphp.Init(
+		frankenphp.WithWorkers("bg", testDataDir+"background-worker-named.php", 0,
+			frankenphp.WithWorkerBackground()),
+		frankenphp.WithNumThreads(3),
+	))
+	t.Cleanup(frankenphp.Shutdown)
+
+	php := `<?php
+try {
+    frankenphp_ensure_background_worker(['bg', 42], 1.0);
+    echo "FAIL no error";
+} catch (TypeError $e) {
+    echo "OK ", $e->getMessage();
+}`
+	tmp := testDataDir + "bg-batch-nonstring.php"
+	require.NoError(t, os.WriteFile(tmp, []byte(php), 0644))
+	t.Cleanup(func() { _ = os.Remove(tmp) })
+
+	req := httptest.NewRequest("GET", "http://example.com/bg-batch-nonstring.php", nil)
+	fr, _ := frankenphp.NewRequestWithContext(req, frankenphp.WithRequestDocumentRoot(testDataDir, false))
+	w := httptest.NewRecorder()
+	_ = frankenphp.ServeHTTP(w, fr)
+	body, _ := io.ReadAll(w.Result().Body)
+	assert.Contains(t, string(body), "OK ")
+	assert.Contains(t, string(body), "must contain only strings")
+	assert.NotContains(t, string(body), "FAIL")
+}
+
+// TestBackgroundWorkerServerFlag confirms that a bg worker sees
+// FRANKENPHP_WORKER_BACKGROUND=true alongside FRANKENPHP_WORKER_NAME in
+// $_SERVER, so scripts can branch without checking every function
+// independently.
+func TestBackgroundWorkerServerFlag(t *testing.T) {
+	cwd, _ := os.Getwd()
+	testDataDir := cwd + "/testdata/"
+
+	require.NoError(t, frankenphp.Init(
+		frankenphp.WithWorkers("flag-worker", testDataDir+"background-worker-bg-flag.php", 1,
+			frankenphp.WithWorkerBackground()),
+		frankenphp.WithNumThreads(3),
+	))
+	t.Cleanup(frankenphp.Shutdown)
+
+	// ensure() removes the race between Init returning and the eager
+	// bg-worker thread reaching its first set_vars.
+	php := `<?php
+frankenphp_ensure_background_worker('flag-worker');
+$vars = frankenphp_get_vars('flag-worker');
+echo 'name=', $vars['name'] ?? 'MISSING', "\n";
+echo 'is_background=', var_export($vars['is_background'] ?? 'MISSING', true), "\n";
+`
+	tmp := testDataDir + "bg-flag-reader.php"
+	require.NoError(t, os.WriteFile(tmp, []byte(php), 0644))
+	t.Cleanup(func() { _ = os.Remove(tmp) })
+
+	req := httptest.NewRequest("GET", "http://example.com/bg-flag-reader.php", nil)
+	fr, _ := frankenphp.NewRequestWithContext(req, frankenphp.WithRequestDocumentRoot(testDataDir, false))
+	w := httptest.NewRecorder()
+	_ = frankenphp.ServeHTTP(w, fr)
+	body, _ := io.ReadAll(w.Result().Body)
+	out := string(body)
+
+	assert.Contains(t, out, "name=flag-worker")
+	assert.Contains(t, out, "is_background=true")
+}