feat: add WithRequestBodyTimeout to bound slow request bodies

[iliaal]

Problem

go_read_post loops on request.Body.Read with no per-read deadline. A client that announces a body (or a large Content-Length) then dribbles or stalls holds a PHP thread for the lifetime of the connection. With a bounded thread pool, max_threads such connections exhaust the pool and legitimate requests get rejected at max_wait_time. This is a slow-POST DoS. It's bounded and recoverable, not a code defect, but the default posture is weaker than the common nginx+php-fpm stack, which buffers the body and ships a default client_body_timeout.

What this adds

WithRequestBodyTimeout(d) sets an idle timeout on body reads: the deadline resets before each read via http.ResponseController.SetReadDeadline, so a steady upload of any size succeeds while a stalled one is cut off and the thread is released. Best effort: if the ResponseWriter can't expose a deadline, the read proceeds without one.

The request_body_timeout Caddyfile directive (and its JSON equivalent on php/php_server) exposes the same control. It now defaults to 60s, matching nginx's client_body_timeout, so slow-POST protection is on without configuration. Set request_body_timeout 0 to disable. The library-level WithRequestBodyTimeout zero value still disables it: embedders opt in, only Caddyfile and JSON deployments get the default.

Behavior change: a php_server or php deployment that doesn't set the directive starts enforcing a 60s idle timeout on request body reads after upgrading. The timeout is idle, not total, so a steady upload of any size still completes; only a stalled body is cut off.

Docs: the directive is documented in docs/config.md, and docs/security.md gains a slow-request-body entry under the in-scope attack surface.

Why not just Caddy read_timeout

read_timeout maps to http.Server.ReadTimeout, a total deadline for the entire request including the body, set server-wide. That's the wrong tool for three reasons, which is why it's off by default:

Aspect	read_timeout (ReadTimeout)	WithRequestBodyTimeout
Semantics	total wall-clock for headers+body	idle: fires only on a stall
Large uploads	a slow-but-steady upload hits the cap	steady upload of any size passes
Scope	server-wide	per request / per route
SSE, websockets, Mercure	also bounds long-lived reads, can break them	only the body read

It also does nothing for library users of frankenphp, who have no Caddy. For a deployment with no SSE and no large uploads, read_timeout is the simpler zero-code answer; this option is for the cases it can't express.

[henderkes]

Generally good, but the option is never actually registered in ServeHTTP, so it's never actually taking effect?

[henderkes]

do we want to silently pass a failed read to php as if everything was fine and then expect 200 back? I'm a bit confused here.

[iliaal]

The option does take effect at the library level: it sets fc.requestBodyTimeout, which go_read_post reads to apply the deadline, and ServeHTTP just retrieves that same fc from the request context. But you're right that nothing wired it into the Caddy module, so a Caddyfile deployment couldn't switch it on. I've added a request_body_timeout directive (latest commit) so it's configurable end to end. requestbodytimeout_test.go covers the library path; config_test.go covers the directive parsing.

[henderkes]

Looks good to me now

[alexandre-daubois]

Good to me as well!

[dunglas]

LGTM too, but:

1. Could you also add docs for this new option please?
2. Shouldn't we enable it by default with a reasonable default value?

[iliaal]

Both done in 1f74594.

1. Docs: added request_body_timeout to the php/php_server options in config.md, plus a slow-request-body entry under the in-scope attack surface in security.md.

2. Enabled by default at 60s, matching nginx's client_body_timeout. The deadline is idle (reset before each read), so a steady upload of any size still passes and only a stalled body trips it, which keeps the breakage risk low. To tell an explicit request_body_timeout 0 (disable) apart from "unset", RequestBodyTimeout is now a *caddy.Duration. The library-level WithRequestBodyTimeout zero value stays disabled, so only Caddyfile and JSON deployments pick up the default.

Worth calling out in the release notes: a deployment that doesn't set the directive starts enforcing the 60s idle timeout after upgrading.