docs+test: clarify non-worker mode cost, add edge-case tests

Docs: "same behavior every request" wording was misleading. In
non-worker mode, only the first request to a given name pays the
lazy-start cost; subsequent calls see the worker already reserved
and return almost immediately.

Tests: add coverage for three edge cases of
frankenphp_require_background_worker():
- Empty name -> ValueError
- Negative timeout -> ValueError
- timeout=0 -> must not hang (returns promptly, any error flavor)

Author: nicolas-grekas

docs/background-workers.md

@@ -48,7 +48,7 @@ Declares a dependency on a background worker. Behavior depends on the caller con
 
 - **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. Same behavior every request.
+- **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.
 
 ```php
 // HTTP worker (bootstrap)

frankenphp_test.go

@@ -1009,6 +1009,28 @@ func TestBackgroundWorkerBootFailureError(t *testing.T) {
 	})
 }
 
+func TestBackgroundWorkerRequireEdgeCases(t *testing.T) {
+	cwd, _ := os.Getwd()
+	entrypoint := cwd + "/testdata/background-worker-with-argv.php"
+
+	runTest(t, func(handler func(http.ResponseWriter, *http.Request), _ *httptest.Server, _ int) {
+		body, _ := testGet("http://example.com/background-worker-require-edge-cases.php", handler, t)
+		// Empty name and negative timeout are argument validation errors.
+		assert.Contains(t, body, "EMPTY_NAME:value_error")
+		assert.Contains(t, body, "NEG_TIMEOUT:value_error")
+		// timeout=0 must not hang; we accept any error, we just want quick return.
+		assert.Contains(t, body, "ZERO_TIMEOUT:threw_in_under_half_sec")
+	}, &testOptions{
+		workerScript:       "background-worker-require-edge-cases.php",
+		nbWorkers:          1,
+		nbParallelRequests: 1,
+		initOpts: []frankenphp.Option{
+			frankenphp.WithMaxThreads(50),
+			frankenphp.WithWorkers("", entrypoint, 0, frankenphp.WithWorkerBackground()),
+		},
+	})
+}
+
 func TestBackgroundWorkerRuntimeRequireAssertsOnly(t *testing.T) {
 	cwd, _ := os.Getwd()
 	entrypoint := cwd + "/testdata/background-worker-with-argv.php"

testdata/background-worker-require-edge-cases.php

@@ -0,0 +1,38 @@
+<?php
+
+frankenphp_handle_request(function () {
+    $results = [];
+
+    // Empty name rejected with ValueError.
+    try {
+        frankenphp_require_background_worker('');
+        $results[] = 'EMPTY_NAME:no_error';
+    } catch (\ValueError $e) {
+        $results[] = 'EMPTY_NAME:value_error';
+    } catch (\Throwable $e) {
+        $results[] = 'EMPTY_NAME:other:' . get_class($e);
+    }
+
+    // Negative timeout rejected with ValueError.
+    try {
+        frankenphp_require_background_worker('some-worker', -1.0);
+        $results[] = 'NEG_TIMEOUT:no_error';
+    } catch (\ValueError $e) {
+        $results[] = 'NEG_TIMEOUT:value_error';
+    } catch (\Throwable $e) {
+        $results[] = 'NEG_TIMEOUT:other:' . get_class($e);
+    }
+
+    // timeout=0 must not hang. In runtime mode this throws 'not running' for
+    // an unknown worker; the key invariant is that the call returns promptly.
+    $start = microtime(true);
+    try {
+        frankenphp_require_background_worker('never-required-zero', 0.0);
+        $results[] = 'ZERO_TIMEOUT:no_error';
+    } catch (\Throwable $e) {
+        $elapsed = microtime(true) - $start;
+        $results[] = 'ZERO_TIMEOUT:threw_in_' . ($elapsed < 0.5 ? 'under_half_sec' : 'over_half_sec');
+    }
+
+    echo implode("\n", $results);
+});