feat: require_background_worker refinements

Collapses the three-mode require semantics into two, moves the
batch-declaration affordance to require instead of get_vars, and
renames require to ensure per @dunglas's concern that "require"
collides with PHP's language keyword (which takes a path).

- frankenphp_require_background_worker -> frankenphp_ensure_background_worker.
  "Ensure" captures the "make sure this is running, start it if it isn't"
  semantic without the keyword collision.

- Tolerant lazy-start inside frankenphp_handle_request: runtime ensure
  now behaves the same as non-worker mode (lazy-start + timeout +
  backoff tolerance). Bootstrap-before-handle_request keeps its
  fail-fast discipline. This lets processes start only the workers
  they actually exercise, instead of over-provisioning by pre-ensuring
  everything that might be needed.

- Multi-name ensure: frankenphp_ensure_background_worker now accepts
  string|array. Batch declaration with a shared deadline, fail-fast on
  any worker's boot failure in bootstrap mode. get_vars loses the array
  form, becoming single-name pure read.

- globalCtx.Done() wired into ensure's select cases, so in-flight
  calls unblock cleanly on FrankenPHP shutdown instead of waiting
  out their timeout.

- Fix: markBackgroundReady() is now called on every set_vars, not just
  the first. Previously sk.readyOnce gated it, leaving isBootingScript
  stuck at true after a crash-restart. That misclassified subsequent
  crashes as boot failures and kept the readyWorkers metric decremented.

Author: nicolas-grekas

background_worker.go

@@ -49,7 +49,7 @@ func (m *backgroundWorkerTestMetrics) DequeuedRequest() {}
 func TestStartBackgroundWorkerFailureIsRetryable(t *testing.T) {
 	lookup := newBackgroundWorkerLookup()
 	lookup.catchAll = newBackgroundWorkerRegistry(testDataPath + "/background-worker-with-argv.php")
-	backgroundLookups = map[string]*backgroundWorkerLookup{"": lookup}
+	backgroundLookups = map[BackgroundScope]*backgroundWorkerLookup{0: lookup}
 	thread := newPHPThread(0)
 	thread.state.Set(state.Ready)
 	thread.handler = &workerThread{
@@ -94,6 +94,54 @@ func TestBackgroundWorkerSetVarsMarksWorkerReady(t *testing.T) {
 	assert.Equal(t, 1, testMetrics.readyCalls)
 }
 
+func TestBackgroundWorkerRestartReReachesReady(t *testing.T) {
+	// After a crash-restart cycle, setupScript flips isBootingScript back to
+	// true and the next set_vars must flip it back to false. Otherwise any
+	// subsequent crash would be misclassified as a boot failure and the
+	// readyWorkers metric would stay decremented.
+	originalMetrics := metrics
+	testMetrics := &backgroundWorkerTestMetrics{}
+	metrics = testMetrics
+	t.Cleanup(func() {
+		metrics = originalMetrics
+	})
+
+	handler := &backgroundWorkerThread{
+		thread: newPHPThread(0),
+		worker: &worker{
+			name:                   "background-worker",
+			fileName:               "background-worker.php",
+			maxConsecutiveFailures: -1,
+			backgroundWorker:       &backgroundWorkerState{ready: make(chan struct{})},
+		},
+		isBootingScript: true,
+	}
+
+	// First boot reaches ready.
+	handler.markBackgroundReady()
+	assert.False(t, handler.isBootingScript)
+	assert.Equal(t, 1, testMetrics.readyCalls)
+
+	// Worker crashes after ready: exit status != 0, isBootingScript == false.
+	handler.afterScriptExecution(1)
+	require.Len(t, testMetrics.stopCalls, 1)
+	assert.Equal(t, StopReason(StopReasonCrash), testMetrics.stopCalls[0])
+
+	// Restart: setupScript would set isBootingScript = true again.
+	handler.isBootingScript = true
+
+	// Next set_vars call must flip it back to false and increment ReadyWorker.
+	handler.markBackgroundReady()
+	assert.False(t, handler.isBootingScript)
+	assert.Equal(t, 2, testMetrics.readyCalls)
+
+	// A second crash at this point must still be classified as Crash, not BootFailure.
+	testMetrics.stopCalls = nil
+	handler.afterScriptExecution(1)
+	require.Len(t, testMetrics.stopCalls, 1)
+	assert.Equal(t, StopReason(StopReasonCrash), testMetrics.stopCalls[0])
+}
+
 func TestBackgroundWorkerBootFailureStaysBootFailureUntilReady(t *testing.T) {
 	originalMetrics := metrics
 	testMetrics := &backgroundWorkerTestMetrics{}

background_worker_test.go

@@ -166,11 +166,12 @@ func unmarshalWorker(d *caddyfile.Dispenser) (workerConfig, error) {
 		if wc.Num > 1 {
 			return wc, d.Err(`"num" > 1 is not yet supported for background workers`)
 		}
-		if wc.MaxThreads > 1 {
-			return wc, d.Err(`"max_threads" > 1 is not yet supported for background workers`)
+		// For named bg workers, max_threads means threads-per-worker (not yet
+		// supported beyond 1). For catch-all (no name), it means the max
+		// number of lazily-started instances, which is a legitimate user knob.
+		if wc.Name != "" && wc.MaxThreads > 1 {
+			return wc, d.Err(`"max_threads" > 1 is not yet supported for named background workers`)
 		}
-		// MaxConsecutiveFailures defaults to 6 (same as HTTP workers)
-		// via defaultMaxConsecutiveFailures in options.go
 	}
 
 	if frankenphp.EmbeddedAppPath != "" && filepath.IsLocal(wc.FileName) {

caddy/workerconfig.go

@@ -41,13 +41,15 @@ func TestBackgroundWorkerFunctionsHiddenInCLI(t *testing.T) {
 	stdoutStderr, err := cmd.CombinedOutput()
 	assert.NoError(t, err)
 
+	// The frankenphp module is not loaded in CLI mode (the embed SAPI is used
+	// without registering the frankenphp extension), so all frankenphp_*
+	// functions are absent. Library code can rely on function_exists() to
+	// degrade gracefully.
 	out := string(stdoutStderr)
-	assert.Contains(t, out, "frankenphp_require_background_worker:hidden")
+	assert.Contains(t, out, "frankenphp_ensure_background_worker:hidden")
 	assert.Contains(t, out, "frankenphp_set_vars:hidden")
 	assert.Contains(t, out, "frankenphp_get_vars:hidden")
 	assert.Contains(t, out, "frankenphp_get_worker_handle:hidden")
-	// unrelated functions must remain available
-	assert.Contains(t, out, "frankenphp_log:exists")
 }
 
 func TestExecuteCLICode(t *testing.T) {

cli_test.go

@@ -7,7 +7,7 @@ They observe their environment and publish variables that HTTP threads (both [wo
 
 1. A background worker runs its own event loop (subscribe to Redis, watch files, poll an API...)
 2. It calls `frankenphp_set_vars()` to publish a snapshot of key-value pairs
-3. HTTP threads call `frankenphp_require_background_worker()` to declare a dependency and ensure the worker is running (lazy-started if needed, blocks until it has published at least once)
+3. HTTP threads call `frankenphp_ensure_background_worker()` to declare a dependency and ensure the worker is running (lazy-started if needed, blocks until it has published at least once)
 4. HTTP threads then call `frankenphp_get_vars()` to read the latest snapshot (pure read, no blocking)
 
 ## Configuration
@@ -27,59 +27,56 @@ example.com {
             name feature-flags
         }
 
-        # Catch-all - handles any unlisted name via require_background_worker()
+        # Catch-all - handles any unlisted name via ensure_background_worker()
         worker /app/bin/console {
             background
         }
     }
 }
 ```
 
-- **Named** (with `name`): lazy-started on first `require_background_worker()` call, or auto-started at boot if `num 1` is set.
+- **Named** (with `name`): lazy-started on first `ensure_background_worker()` call, or auto-started at boot if `num 1` is set.
 - **Catch-all** (no `name`): lazy-started on demand too, for any name not matched by a `name` directive. Use `max_threads` to cap how many can be created (defaults to 16). Not declaring a catch-all forbids unlisted names.
 - Each `php_server` block has its own isolated scope - two blocks can use the same worker names without conflict.
 - `max_consecutive_failures`, `env`, and `watch` work the same as HTTP workers.
 
 ## PHP API
 
-### `frankenphp_require_background_worker(string $name, float $timeout = 30.0): void`
+### `frankenphp_ensure_background_worker(string|array $name, float $timeout = 30.0): void`
 
-Declares a dependency on a background worker. Behavior depends on the caller context:
+Declares a dependency on one or more background workers. Pass a single name or an array of names for batch dependency declaration. The timeout applies across all names in a single call. Behavior depends on the caller context:
 
-- **In an HTTP worker script, before `frankenphp_handle_request()` (bootstrap)**: lazy-starts the worker (at-most-once) if not already running, blocks until it has called `set_vars()` at least once. Fails fast on boot failure (no exponential-backoff tolerance): if the worker's first boot attempts fail, the exception is thrown right away with the captured details. Use this to declare dependencies up front.
-- **In an HTTP worker script, inside `frankenphp_handle_request()` (runtime)**: assert-only. The worker must already be running (declared with `num 1` in Caddyfile or previously required during bootstrap). Never lazy-starts. Throws immediately if the name isn't known. Use this to assert a dependency without starting anything.
-- **In non-worker mode (classic request-per-process)**: lazy-starts the worker and waits up to `$timeout`, tolerating transient boot failures via exponential backoff. The first request to a given name pays the startup cost; subsequent requests in the same FrankenPHP process see the worker already reserved and return almost immediately.
+- **In an HTTP worker script, before `frankenphp_handle_request()` (bootstrap)**: lazy-starts the worker (at-most-once) if not already running, blocks until it has called `set_vars()` at least once. Fails fast on boot failure (no exponential-backoff tolerance): if the worker's first boot attempts fail, the exception is thrown right away with the captured details. Use this to declare dependencies up front so broken deps visibly fail the HTTP worker rather than let it serve degraded traffic.
+- **Everywhere else (inside `frankenphp_handle_request()`, or classic request-per-process)**: lazy-starts the worker and waits up to `$timeout`, tolerating transient boot failures via exponential backoff. The first caller pays the startup cost; subsequent callers in the same FrankenPHP process see the worker already reserved and return almost immediately. This supports the common pattern of library code loaded after bootstrap declaring its own dependencies lazily.
 
 ```php
 // HTTP worker (bootstrap)
-frankenphp_require_background_worker('redis-watcher'); // fail-fast
+frankenphp_ensure_background_worker('redis-watcher'); // fail-fast
 
 while (frankenphp_handle_request(function () {
     $cfg = frankenphp_get_vars('redis-watcher'); // pure read
 })) { gc_collect_cycles(); }
 
 // Non-worker mode (every request)
-frankenphp_require_background_worker('redis-watcher'); // tolerant
+frankenphp_ensure_background_worker('redis-watcher'); // tolerant
 $cfg = frankenphp_get_vars('redis-watcher');
 ```
 
 - Throws `RuntimeException` on timeout, missing entrypoint, or boot failure. The exception contains the captured failure details when available: resolved entrypoint path, exit status, number of attempts, and the last PHP error (message, file, line).
 - Pick a short `$timeout` (e.g. `1.0`) to fail fast; pick a longer one to tolerate slow/flaky startups.
 
-### `frankenphp_get_vars(string|array $name): array`
+### `frankenphp_get_vars(string $name): array`
 
 Pure read: returns the latest published vars from a running background worker. Does not start workers or wait for them to become ready.
 
 ```php
 $redis = frankenphp_get_vars('redis-watcher');
 // ['MASTER_HOST' => '10.0.0.1', 'MASTER_PORT' => 6379]
-
-$all = frankenphp_get_vars(['redis-watcher', 'feature-flags']);
-// ['redis-watcher' => [...], 'feature-flags' => [...]]
 ```
 
-- Throws `RuntimeException` if the worker isn't running or hasn't called `set_vars()` yet. Call `frankenphp_require_background_worker()` first to ensure readiness.
+- Throws `RuntimeException` if the worker isn't running or hasn't called `set_vars()` yet. Call `frankenphp_ensure_background_worker()` first to ensure readiness.
 - Within a single HTTP request, repeated calls with the same name return the same cached array, `===` comparisons are O(1).
+- To read several workers, call `get_vars()` multiple times (each call is an O(1) lock-free read after the first per request).
 - Works in both worker and non-worker mode.
 
 ### `frankenphp_set_vars(array $vars): void`
@@ -197,7 +194,7 @@ $app = new App();
 $app->boot();
 
 // Declare dependencies once at bootstrap
-frankenphp_require_background_worker('config-watcher');
+frankenphp_ensure_background_worker('config-watcher');
 
 while (frankenphp_handle_request(function () use ($app) {
     $config = frankenphp_get_vars('config-watcher'); // pure read
@@ -215,18 +212,18 @@ while (frankenphp_handle_request(function () use ($app) {
 <?php
 // public/index.php - classic request-per-process
 
-frankenphp_require_background_worker('config-watcher');
+frankenphp_ensure_background_worker('config-watcher');
 $config = frankenphp_get_vars('config-watcher');
 // ... handle the request
 ```
 
 ### Graceful Degradation
 
-The `frankenphp_require_background_worker`, `frankenphp_set_vars`, `frankenphp_get_vars`, and `frankenphp_get_worker_handle` functions are only exposed when FrankenPHP runs in SAPI mode (HTTP server). In CLI mode (`frankenphp php-cli ...`), they are hidden, so `function_exists()` returns `false`. Library code can rely on this to degrade gracefully:
+In CLI mode (`frankenphp php-cli ...`), the frankenphp extension is not loaded, so `frankenphp_ensure_background_worker` and friends are absent. `function_exists()` returns `false`, allowing library code to degrade gracefully:
 
 ```php
 if (function_exists('frankenphp_get_vars')) {
-    frankenphp_require_background_worker('config-watcher');
+    frankenphp_ensure_background_worker('config-watcher');
     $config = frankenphp_get_vars('config-watcher');
 } else {
     $config = ['MASTER_HOST' => getenv('REDIS_HOST') ?: '127.0.0.1'];