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: 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:

  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 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.
TimeoutBuilder
Builder for constructing a Timeout with individual phase durations.

Enums§

TimeoutPhase
Identifies the phase of a request that timed out.