feat: background workers (config + ensure)

bgworker_test.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")
+}

bgworkerbatch_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")
+}