Expand description
Phase-aware timeout configuration.
Timeouts are applied per-phase during the request lifecycle. Each phase measures a specific segment of the request:
- Pool: time waiting for a connection slot from the pool.
- Connect: time to establish the TCP connection and TLS handshake (including DNS resolution).
ProxyConnect: TCP connection to the proxy server. Only applies when a proxy is configured.ProxyTls: TLS handshake over a CONNECT tunnel to the proxy. Only applies to HTTPS targets routed through an HTTP proxy.- Write: time for the request body producer to yield each chunk. Only applies to streamed request bodies; buffered bodies complete synchronously.
- Read: time to wait for response headers and each response body chunk. The deadline resets on every chunk arrival.
- Total: wall-clock cap across the entire request lifecycle.
§Proxy timeout phases
When a request is routed through a proxy, the connect phase splits into two sub-phases:
ProxyConnect— the TCP connection from the client to the proxy.ProxyTls— the TLS handshake over the CONNECT tunnel (HTTPS targets only).
After the tunnel is established, regular Connect, Send, and
Receive semantics apply to the destination.
§Enforcement
- Pool and Total are enforced with
tokio::time::timeout. - Read is enforced by a per-chunk wrapper stream that fires
Error::Timeout { phase: Read }if no chunk arrives within the configured duration. The deadline resets on every chunk. - Write is enforced by a per-chunk wrapper stream that fires
Error::Timeout { phase: Write }if the producer does not yield the next chunk within the configured duration. The deadline resets on every chunk. - Connect is enforced by wrapping the underlying connector with a
timeout that bounds the entire connection-establishment phase (DNS
resolution, TCP connect, and TLS handshake). Fires
Error::Timeout { phase: Connect }if the connection is not established within the configured duration.
When a scalar timeout is provided (e.g. Timeout::from_secs(5)), it
applies to pool, connect, write, and read phases. The total timeout is
not set by scalar constructors unless explicitly specified.
Request-level timeout overrides client-level timeout on a per-field basis: only the fields present in the request-level timeout replace the corresponding client-level fields.
Structs§
- Timeout
- Phase-aware timeout configuration for a request.
- Timeout
Builder - Builder for constructing a
Timeoutwith individual phase durations.
Enums§
- Timeout
Phase - Identifies the phase of a request that timed out.