feat(worker): add per-request worker_timeout (hard request timeout)

[mansurs]

What

Adds an experimental worker_timeout worker option: a hard per-request timeout for worker mode — the worker-mode equivalent of PHP-FPM's request_terminate_timeout. When a worker request runs longer than the timeout, FrankenPHP aborts it with a fatal:

Worker request timeout of N second(s) exceeded

and the worker script restarts cleanly to serve the next request. No userland code is required.

Configurable per worker:

frankenphp {
    worker {
        file /path/to/worker.php
        worker_timeout 30s
    }
}

…and via the Go API: WithWorkerTimeout(30 * time.Second). Defaults to 0 (disabled).

Why this is more than max_execution_time

max_execution_time does not count time spent inside a blocking call — so a worker stuck on a slow SELECT SLEEP(30), a hung Redis/Elasticsearch/HTTP read, or a black-holed connect() holds its thread until the call returns on its own. Worse, a signal/EINTR alone cannot abort such a call: PHP retries EINTR, and mysqlnd even removes its socket from EG(regular_list), so it isn't reachable via PHP's resource list. (Verified: even PHP's own max_execution_time can't stop a SELECT SLEEP(30).)

How it works

A time.AfterFunc watchdog is armed per request (epoch-guarded, cancelled on finish). On fire it:

1. Sets a per-thread pending flag + EG(vm_interrupt) (reusing the existing force-kill slot — no new signal path), so a custom zend_interrupt_function raises the fatal at the next opcode boundary.
2. On Linux, inspects what the thread is parked in via /proc/self/task/<tid>/syscall and shuts down the socket(s) involved so a retried blocking read fails terminally. Only sockets are aborted this way (a read blocked on a file or pipe is left alone):
   • read / recvfrom / recvmsg / connect → the fd is the syscall's first argument;
   • poll / ppoll → the struct pollfd array is read from the process's own address space with process_vm_readv(2) (PHP's stream layer — and the Redis/HTTP/DB clients built on it — always polls before reading). Both syscalls are matched: glibc/musl implement poll() via the dedicated poll syscall on arches that have one (amd64, 386, arm) and via ppoll only where they don't (arm64, riscv64, loong64);
   • epoll_wait / epoll_pwait → watched fds are enumerated from /proc/self/fdinfo/<epfd> (covers own-loop clients like curl_multi, gRPC).
3. Wakes EINTR-abortable waits (a long sleep()) via the realtime kill signal.

Safety: every fd is confirmed to be a socket before shutdown, and after recovering a pointer/table-derived fd the thread's syscall is re-read to confirm it is still parked there on the same argument — so a stale pointer or a reused fd cannot close an unrelated descriptor. The /proc and process_vm_readv reads are same-process, read-only, need no ptrace privilege, and fail closed under a restrictive seccomp policy.

Platform support / limits

• Linux: full — including aborting an in-flight blocking socket read (the DB/Redis/HTTP case).
• FreeBSD: sleep() and CPU overruns via the realtime signal; the fd-shutdown is Linux-only.
• macOS / Windows: only the VM-interrupt flag is set — CPU-bound overruns are caught at the next opcode boundary, but a blocking syscall already in progress cannot be unblocked.
• Not covered: select-based event loops (rare on Linux, where poll is preferred) and tight CPU loops inside a C extension that swallow EINTR.

Tests

• TestWorkerTimeout_* (interrupts slow request, interrupts a blocking socket read, does-not-fire-on-fast, disabled, pool-does-not-cross-signals) — all under -race.
• Unit tests for the Linux building blocks: process_vm_readv round-trip, socket-vs-file classification, epoll fdinfo enumeration.
• Caddyfile parsing tests for worker_timeout.
• No regressions in the existing worker / force-kill suites.

Manual verification

Verified end-to-end on linux/arm64 against MariaDB 11.8 (PDO/mysqlnd):

Query	worker_timeout	Result
SELECT SLEEP(0)	2s	200, ~5 ms
SELECT SLEEP(30)	2s	aborts at 2.008 s — Worker request timeout of 2 second(s) exceeded
SELECT SLEEP(0)	2s	200, ~12 ms — worker reconnected and recovered

Docs added in docs/worker.md (and docs/config.md).

[AlliBalliBaba]

Just quickly skimming over this, you should probably use go timers, otherwise this ends up being way too complex

[mansurs]

Thanks for skimming through! It actually does use a Go timer already: the whole thing is driven by a time.AfterFunc that gets armed per request and cancelled on finish. The C and /proc stuff isn't there to detect the timeout, it's there for the hard part: actually getting the thread back.

A timer alone just can't unblock a thread sitting in a blocking syscall. Cgo calls aren't preemptible and PHP happily retries EINTR, so signals don't help either. The best a pure Go version could do is send the client a 504 and walk away while the thread stays stuck, potentially forever on a black-holed connection. That's the exact pool exhaustion this option is meant to prevent. And once the blocking call finally returns, the script would keep running blind and cause side effects long after the client got its error.

[AlliBalliBaba]

Oh so all the platform specific code is just for interrupting a syscall. I was under the impression that the kill signal here would be enough

frankenphp/frankenphp.c

Line 188 in 3f56208

void frankenphp_force_kill_thread(force_kill_slot slot) {

Haven't tried it yet though with something like SELECT SLEEP(30).

There's also a relevant PR in php-src on this topic.