feat: background workers (config + ensure)

[nicolas-grekas]

feat: background workers (config + ensure)

First half of the split suggested in #2287. Lands a minimum-viable background-worker subsystem: config surface, lifecycle, lazy-start via ensure(), per-php_server scoping, named pools, multi-entrypoint, plus a $_SERVER flag for bg-aware scripts. The worker-to-HTTP shared-state APIs (frankenphp_set_vars / frankenphp_get_vars) and the docs are deferred to a follow-up PR — they're independent and easier to review separately.

What lands

PHP API

• frankenphp_ensure_background_worker(string|array $name): void — declares a dependency on one or more bg workers. Fire-and-forget: lazy-starts the named worker (or pulls from a catch-all) if not already running, returns once a thread has been launched. Validates input upfront (ValueError for empty array / empty string / duplicate names; TypeError for non-string elements) so a bad batch never leaves a half-spawned set behind.
• frankenphp_get_worker_handle(): resource — readable stream that signals graceful shutdown. PHP scripts park on stream_select; FrankenPHP closes the write end during drain so select wakes with EOF.

In CLI mode these functions aren't exposed.

Caddyfile

php_server {
    # HTTP worker (unchanged)
    worker public/index.php { num 4 }

    # Named bg worker, eagerly started
    worker bin/jobs.php {
        background
        name job-runner
        num 1
    }

    # Catch-all bg worker, instantiated lazily by ensure(name)
    worker bin/jobs.php {
        background
        max_threads 16
    }
}

• background marks a worker as non-HTTP.
• name pins an exact worker name; declarations without name are catch-alls for lazy-started instances.
• num on a named bg worker eagerly starts that many instances; num 0 (or omitted) defers start until ensure().
• max_threads on a catch-all caps how many distinct lazy-started instances it can host.
• max_consecutive_failures defaults to 6 (same as HTTP workers).
• max_execution_time is automatically disabled for bg workers.

Go API

• WithWorkerBackground() marks a worker declaration as background.
• WithWorkerBackgroundScope(scope) tags a declaration with a scope.
• WithRequestBackgroundScope(scope) tags a request so ensure() from a regular HTTP request resolves to the right block's lookup.
• NextBackgroundWorkerScope() hands out a fresh BackgroundScope value (opaque int under the hood; zero is the global/embed scope).

Per-php_server scoping

Each php_server block gets its own scope. The same user-facing worker name can live in multiple blocks without collision; ensure() resolves through the calling thread's scope (worker handler → request context → global).

Pools and multi-entrypoint

• num > 1 on a named bg worker spawns N threads sharing the same name. Each thread has its own stop pipe so drain can wake them independently.
• Two named bg workers in the same scope can share an entrypoint file. They keep independent options (env, watch mode, failure policy).

Server variables

• $_SERVER['FRANKENPHP_WORKER_NAME'] carries the resolved worker name (catch-all instances see the name they were started under).
• $_SERVER['FRANKENPHP_WORKER_BACKGROUND'] = true for bg workers — single-key branch for "am I a bg worker?".

Lifecycle

• Crash recovery: quadratic backoff capped at 1s; max_consecutive_failures aborts startup if hit during the boot phase.
• Graceful shutdown: stop pipe closes (EOF), workers exit cleanly. After a 30s grace period, a best-effort force-kill drill (per feat: cross-platform force-kill primitive for stuck PHP threads #2365) interrupts threads stuck in blocking syscalls.

What's deferred

A follow-up PR adds:

• frankenphp_set_vars(array $vars): void — publish persistent vars from a bg worker.
• frankenphp_get_vars(string $name): array — pure read, with generational cache so repeated calls within a request return the same array instance (=== is O(1)).
• A frankenphp_set_vars-driven readiness signal that lets ensure() block until a worker has bootstrapped (turning fire-and-forget into a stronger contract without an API change).
• The full docs/background-workers.md reference.

That split keeps the surfaces independent: this PR is the lifecycle/wiring; the follow-up is the data plane.

Tests

End-to-end tests use file sentinels (workers touch a path provided via env) instead of cross-thread observation, since this PR has no shared-state API yet:

• TestBackgroundWorkerLifecycle / TestBackgroundWorkerCrashRestarts / TestBackgroundWorkerWithoutHTTP
• TestBackgroundWorkerRestartForceKillsStuckThread (force-kill drill on a bg worker stuck in sleep(60))
• TestEnsureBackgroundWorkerNamedLazy / TestEnsureBackgroundWorkerCatchAll / TestEnsureBackgroundWorkerCatchAllCap / TestEnsureBackgroundWorkerUndeclared
• TestNextBackgroundWorkerScopeIsDistinct / TestBackgroundWorkerSameNameDifferentScope / TestBackgroundWorkerCatchAllPerScope
• TestBackgroundWorkerPool / TestBackgroundWorkerMultiEntrypoint
• TestEnsureBackgroundWorkerBatch (and the three validation-error variants)
• TestBackgroundWorkerBgFlag

Test plan

• go test ./... clean
• Sanitizers (asan, msan) clean
• Manual: declare a named bg worker, observe its sentinel; restart it via RestartWorkers(), observe re-spawn
• Manual: declare two php_server blocks with same-named bg workers, verify they don't collide