add warnings about limitations of idle-timeout

[pjfanning]

The idle-timeout does catch completely idle connections, but an attacker sending one byte per second would keep the connection alive indefinitely since data is flowing. The request timeout only starts after the entity is complete.

The real mitigations users can apply:

• Lower idle-timeout for untrusted clients
• Use max-content-length to bound total entity size
• Add a reverse proxy (nginx, etc.) that has its own slowloris protections

Adding a per-entity receive timeout to the framework would be a significant feature.

[mkurz]

Findings

1. Medium: the timeout direction is described incorrectly.

   The new comment says it triggers when “no data is received.” Pekko uses bidirectionalIdleTimeout, so traffic in either direction resets it. This should say “when no bytes are sent or received.” Implementation

2. Medium: the suggested mitigations could imply stronger protection than they provide.

   Lowering idle-timeout only forces an attacker to send bytes more frequently. max-content-length limits entity bytes, but does not impose a receive deadline, protect slowly delivered headers, or help until the entity stream is materialized. Entity-limit semantics

   The comment should explicitly say these settings reduce exposure but do not bound request duration. The reverse-proxy or application-level timeout recommendation from the PR body should be retained.

3. Low: the canonical timeout documentation remains incomplete.

   The same limitation should be added to docs/src/main/paradox/common/timeouts.md, where idle-timeout is documented publicly. That page already correctly describes the timeout as bidirectional. Timeout documentation

Suggested wording:

# This is a bidirectional inactivity timeout. It triggers only when no
# bytes are sent or received for the configured duration. Traffic in
# either direction, including a client sending bytes at intervals shorter
# than the timeout, keeps the connection alive; it is not an overall
# request-receive timeout. Lowering this value and configuring
# pekko.http.server.parsing.max-content-length reduce exposure but do not
# bound request duration. Use an appropriately configured reverse proxy or
# application-level entity timeout when a hard receive deadline is required.

[pjfanning]

Thanks @mkurz - changed as suggested.

I'll have a look at docs/src/main/paradox/common/timeouts.md