tez
tez is a lightweight, ergonomic, and fast high-level HTTP client for Rust
SDKs and services.
Quick start
# async
Client::new() builds a client with production defaults. Use
Client::builder() for a base URL, authentication, default headers, timeouts,
redirects, retries, TLS, proxies, or cookies.
Requests
Verb helpers accept a URL or RequestBuilder and send immediately:
# async
The available helpers are get, post, put, patch, delete, head,
options, trace, and query. Use Client::request for another method.
Client::send sends an already-built Request without applying the client's
base URL, default headers, or default authentication.
Request builders support:
- standard
HeaderMap,HeaderName,HeaderValue, andMethodvalues; - basic, bearer, header API-key, and query API-key authentication;
- serializable query parameters;
- buffered bytes, text, JSON, and URL-encoded forms;
- streaming and multipart bodies; and
- a request-specific total timeout.
Client authentication and sensitive default headers require a base URL. They
are sent only to that origin and are stripped from cross-origin redirects.
TRACE requests reject bodies and credentials. Routing, framing, hop-by-hop,
and upgrade headers are managed by the client.
Bodies and responses
Body distinguishes no body (Body::default()) from a present zero-byte body
(Body::empty()). Buffered bodies can be replayed for redirects and retries.
Body::stream accepts an owned BodySource that yields BodyFrame values
containing data chunks or trailers.
A response is returned after final headers arrive; the body remains streaming.
Use body_mut().next_chunk() for incremental reads, or one of the bounded
helpers:
bytescollects decoded bytes;textvalidates UTF-8;jsondeserializes JSON;collectkeeps the response metadata and buffers its body; anddiscarddrains the body so the connection can be reused.
The default body limit is 16 MiB for collection helpers. Manual streaming is not capped by that limit. The total deadline and read-idle timeout still apply. Trailers are available after the body reaches end-of-stream.
Every HTTP status is a successful Response; callers decide which statuses are
acceptable. Responses also expose the negotiated HTTP version, effective URL,
redirect count, repeated headers, and peer address when known.
Redirects and retries
Redirects do not follow by default. Opt in with Redirect::Limit or
Redirect::FollowAll:
#
The hard redirect ceiling is ten hops. Redirect cycles fail explicitly. HTTPS-to-HTTP redirects and unusable locations return the current readable 3xx response. A redirect that needs a body is followed only when the body can be replayed.
Retries are also opt in:
#
The attempt count includes the first request and must be between one and five.
Only idempotent requests with replayable bodies retry. Retryable responses are
408, 425, 429, 500, 502, 503, and 504. Retry-After is honored; otherwise the
client uses bounded exponential jitter. Retries never extend the total deadline.
TLS, proxies, and cookies
The default TLS policy uses platform roots and requires TLS 1.2 or newer. Tls
can require HTTPS, require TLS 1.3, add PEM or DER roots, or set a PEM mutual-TLS
identity. An identity must be bound to an HTTPS base URL and is never sent to a
different origin. Mutual TLS cannot be combined with a proxy.
Configure proxies explicitly with Proxy::http, Proxy::https, or
Proxy::all. Proxy::from_environment reads HTTP_PROXY, HTTPS_PROXY, and
NO_PROXY plus their lowercase forms. Lowercase values take precedence, and
uppercase HTTP_PROXY is ignored in CGI environments.
Cookies are opt in through the cookies feature and an explicit shared Jar.
The in-memory jar enforces domain, path, Secure, expiry, and public-suffix rules
and bounds untrusted cookie growth.
Errors and runtime
Error::kind returns a stable ErrorKind such as Request, Url, Connect,
Tls, Timeout, BodyIo, BodyLimit, or Decoding. Redirect and retry errors
also expose structured details. URLs stored in errors are sanitized, and
backend errors are not exposed as sources or downcast targets.
Sending requests requires a Tokio runtime with I/O and time enabled. Standard
#[tokio::main] and #[tokio::test] runtimes meet that requirement. Missing
runtime support returns ErrorKind::Runtime instead of panicking.
Default timeouts are 10 seconds to connect, 30 seconds total, and 30 seconds
between response body reads. ClientBuilder::timeout, connect_timeout,
read_timeout, and body_limit override them.
Cargo features
| Feature | Default | Adds |
|---|---|---|
rustls |
yes | HTTPS with platform trust |
http2 |
yes | HTTP/2 over TLS |
gzip |
yes | Gzip response decoding |
json |
yes | JSON request and response helpers |
multipart |
yes | Streaming multipart forms and files |
cookies |
no | Shared in-memory cookie jar |
socks |
no | SOCKS proxies |
brotli, deflate, zstd |
no | Additional response decoding |