feat: batch ensure + FRANKENPHP_WORKER_BACKGROUND server flag

Two small, related polish steps on the bg-worker surface, landing
together:

- frankenphp_ensure_background_worker now accepts string|array. The
  array form lazy-starts every named worker fire-and-forget, with the
  same semantics as the single-string call repeated N times. Input is
  validated up-front: empty arrays raise ValueError, non-string
  elements raise TypeError, empty-string and duplicate names raise
  ValueError. Validation happens before any worker is started so a bad
  input never leaves a half-spawned batch behind.

- $_SERVER['FRANKENPHP_WORKER_BACKGROUND'] = true in background worker
  scripts, alongside the existing FRANKENPHP_WORKER_NAME wiring. Gives
  scripts a single-key branch for "am I a bg worker?" without having
  to probe other frankenphp_* helpers. Set unconditionally for bg
  workers (catch-all instances with no declared name still see the
  flag, just no name).

- TestEnsureBackgroundWorkerBatch: ensure(['a','b','c']) starts three
  catch-all-resolved instances; assert three per-name sentinels appear.
- TestEnsureBackgroundWorkerBatchEmpty: [] raises ValueError. Driven
  through a PHP fixture that catches the throwable since the
  validation lives in the Zend parameter-parsing path.
- TestEnsureBackgroundWorkerBatchNonString: ['ok-name', 42] raises
  TypeError, same fixture pattern.
- TestEnsureBackgroundWorkerBatchDuplicate: ['dup','dup'] raises
  ValueError (duplicate names rejected, not silently deduped).
- TestBackgroundWorkerBgFlag: bg worker writes var_export() of
  $_SERVER['FRANKENPHP_WORKER_BACKGROUND'] to a sentinel; assert the
  exact value is the bool true.

Author: nicolas-grekas

background_worker_batch_test.go

@@ -0,0 +1,165 @@
+package frankenphp_test
+
+import (
+	"io"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/dunglas/frankenphp"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// serveTestRequest issues an HTTP request through frankenphp against the
+// given script under testdata/ and returns the response body. ErrRejected
+// is treated as a non-fatal outcome so worker-mode quirks don't fail tests
+// that only care about the script's stdout.
+func serveTestRequest(t *testing.T, testDataDir, script, query string) string {
+	t.Helper()
+	url := "http://example.com/" + script
+	if query != "" {
+		url += "?" + query
+	}
+	req := httptest.NewRequest("GET", url, nil)
+	fr, err := frankenphp.NewRequestWithContext(req, frankenphp.WithRequestDocumentRoot(testDataDir, false))
+	require.NoError(t, err)
+
+	w := httptest.NewRecorder()
+	err = frankenphp.ServeHTTP(w, fr)
+	if err != nil {
+		require.ErrorAs(t, err, &frankenphp.ErrRejected{})
+	}
+	body, err := io.ReadAll(w.Result().Body)
+	require.NoError(t, err)
+	return string(body)
+}
+
+// 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) {
+	cwd, _ := os.Getwd()
+	testDataDir := cwd + "/testdata/"
+	tmp := t.TempDir()
+
+	require.NoError(t, frankenphp.Init(
+		frankenphp.WithWorkers("", testDataDir+"background-worker-named.php", 0,
+			frankenphp.WithWorkerBackground(),
+			frankenphp.WithWorkerMaxThreads(8),
+			frankenphp.WithWorkerEnv(map[string]string{"BG_SENTINEL_DIR": tmp}),
+		),
+		frankenphp.WithNumThreads(8),
+	))
+	t.Cleanup(frankenphp.Shutdown)
+
+	body := serveTestRequest(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"} {
+		path := filepath.Join(tmp, name)
+		assert.Eventually(t, func() bool {
+			_, err := os.Stat(path)
+			return err == nil
+		}, 5*time.Second, 10*time.Millisecond,
+			"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) {
+	cwd, _ := os.Getwd()
+	testDataDir := cwd + "/testdata/"
+
+	require.NoError(t, frankenphp.Init(
+		frankenphp.WithWorkers("", testDataDir+"background-worker-named.php", 0,
+			frankenphp.WithWorkerBackground(),
+		),
+		frankenphp.WithNumThreads(2),
+	))
+	t.Cleanup(frankenphp.Shutdown)
+
+	body := serveTestRequest(t, testDataDir, "background-worker-batch-errors.php", "mode=empty")
+	assert.True(t, strings.Contains(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) {
+	cwd, _ := os.Getwd()
+	testDataDir := cwd + "/testdata/"
+
+	require.NoError(t, frankenphp.Init(
+		frankenphp.WithWorkers("", testDataDir+"background-worker-named.php", 0,
+			frankenphp.WithWorkerBackground(),
+		),
+		frankenphp.WithNumThreads(2),
+	))
+	t.Cleanup(frankenphp.Shutdown)
+
+	body := serveTestRequest(t, testDataDir, "background-worker-batch-errors.php", "mode=nonstring")
+	assert.True(t, strings.Contains(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) {
+	cwd, _ := os.Getwd()
+	testDataDir := cwd + "/testdata/"
+
+	require.NoError(t, frankenphp.Init(
+		frankenphp.WithWorkers("", testDataDir+"background-worker-named.php", 0,
+			frankenphp.WithWorkerBackground(),
+		),
+		frankenphp.WithNumThreads(2),
+	))
+	t.Cleanup(frankenphp.Shutdown)
+
+	body := serveTestRequest(t, testDataDir, "background-worker-batch-errors.php", "mode=duplicate")
+	assert.True(t, strings.Contains(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) {
+	cwd, _ := os.Getwd()
+	testDataDir := cwd + "/testdata/"
+
+	tmp := t.TempDir()
+	sentinel := filepath.Join(tmp, "bg-flag.sentinel")
+
+	require.NoError(t, frankenphp.Init(
+		frankenphp.WithWorkers("bg-flag", testDataDir+"background-worker-bg-flag.php", 1,
+			frankenphp.WithWorkerBackground(),
+			frankenphp.WithWorkerEnv(map[string]string{"BG_SENTINEL": sentinel}),
+		),
+		frankenphp.WithNumThreads(2),
+	))
+	t.Cleanup(frankenphp.Shutdown)
+
+	require.Eventually(t, func() bool {
+		_, err := os.Stat(sentinel)
+		return err == nil
+	}, 5*time.Second, 10*time.Millisecond,
+		"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")
+}

background_worker_ensure_test.go

@@ -12,18 +12,13 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
-// waitForSentinel polls for a file to appear; returns true if it does
-// before the deadline.
-func waitForSentinel(t *testing.T, path string, within time.Duration) bool {
-	t.Helper()
-	deadline := time.Now().Add(within)
-	for time.Now().Before(deadline) {
-		if _, err := os.Stat(path); err == nil {
-			return true
-		}
-		time.Sleep(10 * time.Millisecond)
+// sentinelExists is a predicate suitable for assert.Eventually that returns
+// true once the named file appears on disk.
+func sentinelExists(path string) func() bool {
+	return func() bool {
+		_, err := os.Stat(path)
+		return err == nil
 	}
-	return false
 }
 
 // TestEnsureBackgroundWorkerNamedLazy declares a num=0 named worker, then
@@ -49,7 +44,8 @@ func TestEnsureBackgroundWorkerNamedLazy(t *testing.T) {
 	require.True(t, os.IsNotExist(err), "lazy worker should not have started yet")
 
 	require.NoError(t, ensureBackgroundWorker(nil, "bg-lazy", 5*time.Second))
-	assert.True(t, waitForSentinel(t, filepath.Join(tmp, "bg-lazy"), 5*time.Second),
+	assert.Eventually(t, sentinelExists(filepath.Join(tmp, "bg-lazy")),
+		5*time.Second, 10*time.Millisecond,
 		"ensure() should have lazy-started the named bg worker")
 }
 
@@ -77,7 +73,8 @@ func TestEnsureBackgroundWorkerCatchAll(t *testing.T) {
 	}
 
 	for _, name := range []string{"job-a", "job-b"} {
-		assert.True(t, waitForSentinel(t, filepath.Join(tmp, name), 5*time.Second),
+		assert.Eventually(t, sentinelExists(filepath.Join(tmp, name)),
+			5*time.Second, 10*time.Millisecond,
 			"catch-all instance %q should have written its sentinel", name)
 	}
 }

background_worker_scope_test.go

@@ -136,7 +136,8 @@ func TestBackgroundWorkerCatchAllPerScope(t *testing.T) {
 
 	// Wait for the worker to write its sentinel so we know the right
 	// fixture ran (sanity check that env was inherited from scope A).
-	assert.True(t, waitForSentinel(t, filepath.Join(dirA, "job-a"), 3*time.Second),
+	assert.Eventually(t, sentinelExists(filepath.Join(dirA, "job-a")),
+		3*time.Second, 10*time.Millisecond,
 		"scope A catch-all instance must write its sentinel under scope A's BG_SENTINEL_DIR")
 }
 

background_worker_test.go

@@ -1,7 +1,6 @@
 package frankenphp_test
 
 import (
-	"errors"
 	"io"
 	"net/http/httptest"
 	"os"
@@ -109,11 +108,13 @@ func TestBackgroundWorkerWithoutHTTP(t *testing.T) {
 	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)
+	err = frankenphp.ServeHTTP(w, fr)
+	if err != nil {
+		require.ErrorAs(t, err, &frankenphp.ErrRejected{})
 	}
 
-	body, _ := io.ReadAll(w.Result().Body)
+	body, err := io.ReadAll(w.Result().Body)
+	require.NoError(t, err)
 	assert.True(t, strings.Contains(string(body), "I am by birth a Genevese") || strings.Contains(string(body), "<?php") || len(body) > 0,
 		"expected non-empty body from index.php, got %q", string(body))
 }

background_worker.go bgworker.gobackground_worker.go renamed to bgworker.go

@@ -10,6 +10,7 @@ import (
 	"sync"
 	"sync/atomic"
 	"time"
+	"unsafe"
 )
 
 // defaultMaxBackgroundWorkers is the default safety cap for catch-all
@@ -85,7 +86,7 @@ func (r *backgroundWorkerReady) abort(err error) {
 // declare workers with the same name without conflict. The zero value is
 // the global/embed scope (used when no per-block scope was assigned).
 // Representation is opaque; obtain values via NextBackgroundWorkerScope.
-type BackgroundScope int
+type BackgroundScope uint64
 
 var backgroundScopeCounter atomic.Uint64
 
@@ -439,19 +440,29 @@ func formatEnsureTimeoutError(name string, r *backgroundWorkerReady, timeout tim
 	return fmt.Errorf("background worker %q did not call frankenphp_get_worker_handle() within %s", name, timeout)
 }
 
-// go_frankenphp_ensure_background_worker declares a dependency on a
-// background worker by name. Lazy-starts it if not already running and
-// blocks until it signals readiness (first call to
-// frankenphp_get_worker_handle()), aborts, or the timeout elapses.
-// timeoutMs is in milliseconds; <= 0 means use the default.
+// 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, and the call blocks until every named worker has
+// signalled readiness (first call to frankenphp_get_worker_handle()),
+// aborted, or the per-call timeout has elapsed. The C side has already
+// validated that names is non-empty and that every element is a non-empty
+// unique string. timeoutMs is in milliseconds; <= 0 means use the default.
 //
 //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.int64_t) *C.char {
+func go_frankenphp_ensure_background_worker(threadIndex C.uintptr_t, names **C.char, nameLens *C.size_t, nameCount C.int, timeoutMs C.int64_t) *C.char {
 	thread := phpThreads[threadIndex]
-	goName := C.GoStringN(name, C.int(nameLen))
+	n := int(nameCount)
+	if n <= 0 {
+		return nil
+	}
 	timeout := time.Duration(int64(timeoutMs)) * time.Millisecond
-	if err := ensureBackgroundWorker(thread, goName, timeout); err != nil {
-		return C.CString(err.Error())
+	nameSlice := unsafe.Slice(names, n)
+	nameLenSlice := unsafe.Slice(nameLens, n)
+	for i := 0; i < n; i++ {
+		goName := C.GoStringN(nameSlice[i], C.int(nameLenSlice[i]))
+		if err := ensureBackgroundWorker(thread, goName, timeout); err != nil {
+			return C.CString(err.Error())
+		}
 	}
 	return nil
 }