Skip to main content

Module timeout

Module timeout 

Source
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: after the request body producer completes, time to wait for response headers, then each response body chunk. The deadline resets on each chunk. Early responses do not charge upload time to the read budget.
  • Total: absolute wall-clock deadline across the entire request lifecycle, from logical request start through response-body EOF (or terminal body error), including pool acquisition, transport setup, response headers, body chunks, decompression, and trailers. It never resets on chunk arrival, decoding selection, or first body poll. A body that is first polled after the deadline reports Total without accepting a ready inner chunk.

§Proxy timeout phases

When a request is routed through a proxy, the connect phase splits into two sub-phases:

  1. ProxyConnect — the TCP connection from the client to the proxy.
  2. 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 while waiting for response headers after request body completion on Hyper and UDS routes, then by a per-chunk wrapper stream. The body deadline starts on first body poll and resets on every chunk. Experimental HTTP/3 currently applies this field to response-body progress only; its header wait remains total-bounded.
  • Total is enforced in two stages: tokio::time::timeout bounds the transport future up to response headers, and a crate-private absolute response-body deadline (ResponseDeadline) bounds body streaming through EOF/trailers. The absolute instant never resets; an already-expired deadline wins before polling the inner body, and when both read and total are observably expired at the same poll boundary Total is preferred as the outer lifecycle cap.
  • 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.
TimeoutBuilder
Builder for constructing a Timeout with individual phase durations.

Enums§

TimeoutPhase
Identifies the phase of a request that timed out.