ureq

In ureq 3.x, the library aims for strict semver adherence. However, certain experimental or low-level APIs are located in the unversioned module.

The unversioned module does not follow semver.

This module includes:

• Transport: A trait for writing bespoke transports.
• Resolver: A trait for writing bespoke DNS resolvers.
• unversioned::multipart: Multipart support.

Use these features with caution as their APIs are not yet solidified and may change in minor or patch releases.

By enabling the charset feature, ureq supports receiving character sets other than utf-8.

When calling Body::read_to_string(), the library inspects the Content-Type header (e.g., Content-Type: text/plain; charset=iso-8859-1). If a charset is specified, it attempts to decode the body using that encoding. If the charset is missing or uninterpretable, it falls back to utf-8.

Note: ureq does not currently support encoding specific character sets when sending request bodies.

When reading text bodies (where Content-Type starts with text/), ureq can handle invalid UTF-8 characters by replacing them with a question mark ? (not the standard UTF-8 replacement character).

• For Body::read_to_string(), this lossy behavior is enabled by default.
• For Body::as_reader(), this behavior is disabled by default but can be enabled.

To precisely configure this behavior, use Body::with_config().

In ureq 3.x, you can configure root certificates using the RootCerts enum within TlsConfig. This configuration can be applied at either the Agent level or the Request level.

Available RootCerts variants:

• PlatformVerifier: For rustls, this delegates to the system. For native-tls, this uses the root certificates that native-tls is already picking up (the recommended setting for most users).
• WebPki: Uses the root certificates bundled with ureq.
• Specific: Allows you to provide and set your own specific root certificates.

For basic HTTP tasks, you can use the crate-level convenience functions like ureq::get or ureq::post. These functions allow you to chain methods for headers and then execute the request with .call().

Example of a simple GET request:

let body: String = ureq::get("http://example.com")
    .header("Example-Header", "header value")
    .call()?
    .body_mut()
    .read_to_string()?;

ureq returns errors via Result<T, ureq::Error>. This includes I/O and protocol errors. By default, any HTTP status code in the 4xx or 5xx range is treated as an Error::StatusCode(code).

You can handle these errors using pattern matching:

use ureq::Error;

match ureq::get("http://mypage.example.com/").call() {
    Ok(response) => { /* it worked */},
    Err(Error::StatusCode(code)) => {
        /* the server returned an unexpected status
           code (such as 400, 500 etc) */
    }
    Err(_) => { /* some kind of io/transport/etc error */ }
}

To prevent 4xx/5xx status codes from being treated as errors, use the .http_status_as_error() method on the request builder.

Proxies are configured on an Agent. All requests sent through that agent will use the configured proxy.

• HTTP (CONNECT) proxies: Always available.
• SOCKS4/SOCKS5 proxies: Must be enabled using the socks-proxy feature.

Environment Variables

When creating a default Agent, ureq automatically reads proxy configuration from the following environment variables (checked in order, including lowercase variants):

1. ALL_PROXY
2. HTTPS_PROXY
3. HTTP_PROXY

NO_PROXY can be used to specify hosts that bypass the proxy. It supports:

• Exact hosts
• Wildcard suffixes (*.example.com)
• Dot suffixes (.example.com)
• Match-all (*)

When accessing the body, you can choose between a shared reader (borrowing the body) or an owned reader (consuming the body).

• Shared Reader (as_reader() / with_config()): Borrows the Body. Use this when you want to keep the Response object alive and perform multiple operations.
• Owned Reader (into_reader() / into_with_config()): Consumes the Body. This returns a reader with a 'static lifetime, allowing you to move the reader to another thread or disconnect it from the original response object.

A Form is a collection of Part objects. When a Form is sent as a request body, it generates a unique boundary string. Each Part within the form is then encapsulated between these boundaries, including its own headers (like Content-Disposition and Content-Type).

1. Form::new() initializes a new multipart container with a random boundary.
2. Form::text() or Form::file() are high-level helpers that create and append Parts.
3. Form::part() allows injecting a manually configured Part.
4. RequestBuilder::send(form) triggers the serialization of the entire multipart structure into the request body.