feat: declared background workers + frankenphp_get_worker_handle()

[nicolas-grekas]

A worker marked background runs its script in a loop outside the HTTP request cycle. frankenphp_get_worker_handle() hands the script a stream that reaches EOF when FrankenPHP drains the worker, so it can park on stream_select() or a blocking read and exit gracefully on shutdown, reboot or restart.

PHP API

frankenphp_get_worker_handle(): resource, a stream that reaches EOF when the worker is drained: the Go side closes its end of a per-thread socket pair. A socket pair rather than a pipe so that stream_select() takes the plain socket path on Windows too, where PHP's php_select() only waits properly on sockets before 8.5. Throws when called outside a background worker. Each call returns a fresh stream over the same socket; streams don't own it, so closing one never affects another, and the read timeout is infinite so a blocking read parks as well as stream_select() does.

Go API

WithWorkerBackground(). Background workers attach to a Server through the existing WithWorkerServerScope(). num >= 1 is required (no lazy-start in this build) and the name is mandatory, since it is the script's identity and is exposed as $_SERVER['FRANKENPHP_WORKER'].

Lifecycle

backgroundWorkerThread implements threadHandler and mirrors workerThread's state machine: boot, re-run on cooperative exit (status 0, backoff reset), crash-restart with quadratic backoff, hard failure on max_consecutive_failures during startup only.

A worker counts as ready once it first waits on its handle (stream_select() or a blocking read), the background analog of frankenphp_handle_request(): Init() waits for that point, ready_workers counts from it, and an exit before it is a boot failure whether or not the handle was fetched.

drain() is wired into thread.shutdown() and rebootAllThreads(), so shutdowns and watch-triggered reboots wake parked background workers instead of waiting out the force-kill grace period.

Caddy

background flag inside worker blocks, in both php_server and global ones. name is required, match is rejected. Metrics and logs use the worker name, which server-qualified naming already keeps unique across php_server blocks, so two blocks may declare the same worker name.

Worker names

Names are scoped the way paths already are: unique within a php_server (or among global workers), so two blocks may each declare a worker named queue. A background script sees the declared name in $_SERVER['FRANKENPHP_WORKER'], and WithWorkerName() resolves within the request's server before the global workers. Metrics and logs need a process-wide identity, so a server-scoped worker is reported there as <server name>:<name>; server names get a numeric suffix when two blocks resolve to the same one. The collision-driven renaming in the Caddy module is gone.

Deferred

• frankenphp_ensure_background_worker() and lazy-start machinery
• Catch-all (empty-name) workers
• Shared-state APIs (frankenphp_set_vars / frankenphp_get_vars)
• An orchestrator-style frankenphp_start_background_worker() runtime API; the primitives here are compatible with it

Tests

• TestBackgroundWorkerLifecycle: boots, touches its sentinel, parks on the stop pipe, Shutdown() returns within 10s
• TestBackgroundWorkerCrashRestarts: exit(1) on first boot, the respawned run touches the "restarted" sentinel
• TestBackgroundWorkerOnServer: inherits the server env, FRANKENPHP_WORKER carries the declared name while a global worker reuses it, HTTP requests on the same server still serve
• TestBackgroundWorkerValidation: name required, num >= 1, names unique within a server, request matchers rejected, an early return or a fetch without a wait fails startup
• TestWorkerBackgroundConfig / RequiresName / RejectsMatch: Caddyfile parsing

Supersedes #2543 and #2398.

[henderkes]

Please rewrite the PR description to not be LLM slop reasoning with itself about what it did and why. I've tried reading this three times and I just can't.

[nicolas-grekas]

Sure, I'll let you know when I'm done, for now I just let it do the rebase 😅

[henderkes]

What happens here when a global background worker and a php_server scoped background worker share the same name and are both eligible for the same source file?

[henderkes]

aren't we leaking fd's on every restart then?

[henderkes]

found another one, anyway, have you tested this on windows?

[Copilot]

Pull request overview

Adds declared background PHP workers with graceful stop-stream handling and Caddy configuration support.

Changes:

• Adds background-worker lifecycle, validation, and thread allocation.
• Exposes frankenphp_get_worker_handle().
• Adds Caddy integration, documentation, fixtures, and tests.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
worker.go	Registers and validates background workers.
threadbackgroundworker.go	Implements background-worker lifecycle.
requestoptions.go	Rejects background workers for HTTP requests.
phpthread.go	Drains handlers during shutdown and transitions.
phpmainthread.go	Drains handlers during reboot.
options.go	Adds WithWorkerBackground().
frankenphp.go	Reserves background-worker threads.
frankenphp.c	Implements stop pipes and PHP API.
frankenphp.h	Declares C primitives.
frankenphp.stub.php	Declares the PHP function.
frankenphp_arginfo.h	Registers generated arginfo.
docs/config.md	Documents background configuration.
caddy/workerconfig.go	Parses background worker blocks.
caddy/config_test.go	Tests Caddy parsing and validation.
bgworker_test.go	Tests lifecycle, restart, scope, and validation.
testdata/bgworker/basic.php	Provides lifecycle fixture.
testdata/bgworker/crash.php	Provides restart fixture.
testdata/bgworker/early-return.php	Provides startup-failure fixture.
testdata/bgworker/named.php	Provides named-worker fixture.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[AlliBalliBaba]

Hmm I don't remember the specific reason why background workers are treated separately here. Wouldn't it make sense to just do this and count it into the general pool, like other workers:

if w.num <= 0 {
    if w.isBackgroundWorker {
		opt.workers[i].num = 1
    } else {
		opt.workers[i].num = maxProcs
    }
}

Worker thread count is already added on top of the general thread count. It would only overflow in case someone sets a general cap on global threads, in which case it should probably still honor that cap.

[AlliBalliBaba]

It looks like currently the handle is only used for shutdown. IIRC in the future you'd also want to use the handle to send messages or even requests.

Would it maybe be cleaner to have a separate handle for each? Makes the api look more like we're selecting over different channels, in other words:

frankenphp_get_shutdown_handle(); # instead of frankenphp_get_worker_handle
frankenphp_get_message_handle(); # future scope: can return a dedicated message
frankenphp_get_request_handle(); # future scope: can return a dedicated request object