feat: shared-state APIs (set_vars/get_vars) + readiness wait

Adds the worker-to-HTTP shared-state surface deferred from the
config+ensure split (php#2393):

- frankenphp_set_vars(array $vars): void publishes a snapshot from a
  background worker. Persistent (pemalloc) memory, RWMutex-protected,
  cross-thread safe. Skips work when data is identical (=== check).
- frankenphp_get_vars(string $name): array reads the latest snapshot.
  Pure read; throws if the worker is not running or has not published
  yet.
- ensure_background_worker now blocks until the named worker has called
  set_vars at least once (the readiness signal). The fire-and-forget
  semantics from the config-only PR become a stronger contract here
  with no API change visible to callers.
- Two-mode ensure: fail-fast in HTTP-worker bootstrap (before
  frankenphp_handle_request) so a broken dependency surfaces at boot
  rather than serving degraded traffic; tolerant inside requests so
  the restart-with-backoff cycle can recover from transient boot
  failures.
- Boot-failure capture: the worker's last PHP error (message, file,
  line, exit status) is recorded so ensure() can throw a descriptive
  RuntimeException on timeout.

The persistent storage path uses opcache-immutable arrays (zero-copy
share), interned strings (no copy), and rich type support: null,
scalars, arrays (nested), enums.

Tests cover happy-path roundtrips, type coverage, ensure() blocking
on first set_vars, fail-fast vs tolerant modes, boot-failure
reporting, and the catch-all + scope interactions with vars.

Author: nicolas-grekas

.github/workflows/sanitizers.yaml

@@ -108,7 +108,7 @@ jobs:
       - name: Set CGO flags
         run: |
           {
-            echo "CGO_CFLAGS=$CFLAGS -I${PWD}/watcher/target/include -DFRANKENPHP_TEST $(php-config --includes)"
+            echo "CGO_CFLAGS=$CFLAGS -I${PWD}/watcher/target/include $(php-config --includes)"
             echo "CGO_LDFLAGS=$LDFLAGS $(php-config --ldflags) $(php-config --libs)"
           } >> "$GITHUB_ENV"
       - name: Run tests

.github/workflows/tests.yaml

@@ -62,7 +62,7 @@ jobs:
         # TODO: remove this workaround when fixed upstream
         run: sudo apt-get install --reinstall -y libbrotli-dev
       - name: Set CGO flags
-        run: echo "CGO_CFLAGS=-I${PWD}/watcher/target/include -DFRANKENPHP_TEST $(php-config --includes)" >> "${GITHUB_ENV}"
+        run: echo "CGO_CFLAGS=-I${PWD}/watcher/target/include $(php-config --includes)" >> "${GITHUB_ENV}"
       - name: Build
         run: go build
       - name: Build testcli binary
@@ -138,7 +138,7 @@ jobs:
           echo "GEN_STUB_SCRIPT=${PWD}/php-${PHP_VERSION}/build/gen_stub.php" >> "${GITHUB_ENV}"
       - name: Set CGO flags
         run: |
-          echo "CGO_CFLAGS=-DFRANKENPHP_TEST $(php-config --includes)" >> "${GITHUB_ENV}"
+          echo "CGO_CFLAGS=$(php-config --includes)" >> "${GITHUB_ENV}"
           echo "CGO_LDFLAGS=$(php-config --ldflags) $(php-config --libs)" >> "${GITHUB_ENV}"
       - name: Install gotestsum
         run: go install gotest.tools/gotestsum@latest
@@ -175,7 +175,7 @@ jobs:
       - name: Set CGO flags
         run: |
           {
-           echo "CGO_CFLAGS=-I/opt/homebrew/include/ -DFRANKENPHP_TEST $(php-config --includes)"
+           echo "CGO_CFLAGS=-I/opt/homebrew/include/ $(php-config --includes)"
            echo "CGO_LDFLAGS=-L/opt/homebrew/lib/ $(php-config --ldflags) $(php-config --libs)"
           } >> "${GITHUB_ENV}"
       - name: Build

background_worker_batch_test.go

@@ -1,165 +1,154 @@
 package frankenphp_test
 
 import (
+	"errors"
 	"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.
+// 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/"
-	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),
+		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)
 
-	body := serveTestRequest(t, testDataDir, "background-worker-batch-ensure.php", "")
-	assert.Contains(t, body, "ok", "batch ensure script should echo ok, got: %q", body)
+	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)
 
-	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)
+	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 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.
+// 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("", testDataDir+"background-worker-named.php", 0,
-			frankenphp.WithWorkerBackground(),
-		),
-		frankenphp.WithNumThreads(2),
+		frankenphp.WithWorkers("bg", testDataDir+"background-worker-named.php", 0,
+			frankenphp.WithWorkerBackground()),
+		frankenphp.WithNumThreads(3),
 	))
 	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")
+	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 a non-string element
-// raises a TypeError (PHP's standard for argument-type mismatches inside
-// our parsed array).
+// 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("", testDataDir+"background-worker-named.php", 0,
-			frankenphp.WithWorkerBackground(),
-		),
-		frankenphp.WithNumThreads(2),
+		frankenphp.WithWorkers("bg", testDataDir+"background-worker-named.php", 0,
+			frankenphp.WithWorkerBackground()),
+		frankenphp.WithNumThreads(3),
 	))
 	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")
+	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")
 }
 
-// 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) {
+// 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/"
 
-	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),
+		frankenphp.WithWorkers("flag-worker", testDataDir+"background-worker-bg-flag.php", 1,
+			frankenphp.WithWorkerBackground()),
+		frankenphp.WithNumThreads(3),
 	))
 	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")
+	// 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)
 
-	contents, err := os.ReadFile(sentinel)
-	require.NoError(t, err)
-	assert.Equal(t, "true", string(contents),
-		"$_SERVER['FRANKENPHP_WORKER_BACKGROUND'] should be the bool true")
+	assert.Contains(t, out, "name=flag-worker")
+	assert.Contains(t, out, "is_background=true")
 }