Module http 

The HTTP client every HTTP connector uses (RFC 0013, #880).

Client wraps a reqwest::Client and adds what each HTTP connector used to write for itself, sometimes wrongly:

• Redirects that drop credentials. Redirects are followed here, not by reqwest, so a hop to another origin (scheme, host or port) drops the Authorization, Cookie and Proxy-Authorization headers, every header marked sensitive, and every header named with ClientBuilder::sensitive_header (an API-key header). reqwest’s own policy only knows the standard headers.
• Redirect targets are checked. A redirect into a link-local or cloud instance-metadata address is always refused. Under a reference policy (ClientBuilder::reference_policy, or one scoped over a run with with_reference_policy) the first request and every redirect hop must pass ReferencePolicy::check_url.
• Bounded response reads. Client::bytes / text / json refuse a body above max_response_bytes instead of buffering it whole.
• One error shape. A non-2xx response becomes FaucetError::HttpStatus (body truncated, URL without credentials), a 429 / 503 with Retry-After becomes FaucetError::RateLimited, and a transport error keeps reqwest’s timeout / connect classification with the credentials removed from its URL.
• Retries through CallContext. Client::execute runs a request under a context’s timeout, deadline, retry policy, cancellation and metering.

use faucet_core::http::Client;
use faucet_core::io::CallContext;
use std::time::Duration;

let client = Client::builder()
    .timeout(Duration::from_secs(30))
    .sensitive_header("x-api-key")
    .build()?;
let ctx = CallContext::new().with_retry(faucet_core::RetryPolicy::default());
let resp = client
    .execute(&ctx, "page", || client.get("https://api.example.com/items"))
    .await?;
let body: serde_json::Value = client.json(resp).await?;

reqwest options this builder does not name (compression, mutual TLS, root certificates) are set through ClientBuilder::configure.

Structs

Client

An HTTP client for connectors. Cheap to clone; build one in new() and reuse it. See the module docs.

ClientBuilder

Builds a Client.

ResponseTooLarge

A response body was larger than the client’s max_response_bytes. Carried in FaucetError::Custom; downcast to read it.

Constants

DEFAULT_MAX_REDIRECTS

The most redirects one request follows by default.

DEFAULT_MAX_RESPONSE_BYTES

The largest body Client::bytes buffers by default: 1 GiB.

Functions

current_reference_policy

The reference policy scoped over the current task, if any.

inherit_reference_policy

fut under the reference policy scoped over the current task, for a future about to be spawned onto another task.

is_cross_origin

Whether b is a different origin from a: another scheme, host or port.

status_error

The error for a non-2xx response: FaucetError::RateLimited for a 429 (or a 503 with Retry-After) that states its wait, otherwise FaucetError::HttpStatus with the body truncated to DEFAULT_ERROR_BODY_MAX_LEN bytes and the URL without credentials. Consumes the response.

strip_credentials

Remove every credential-bearing header: the standard ones, every value marked sensitive, and the extra names.

transport_error

A transport error with the credentials removed from its URL.

with_reference_policy

Run fut with policy as the reference policy every Client without its own (ClientBuilder::reference_policy) checks its requests and redirect hops against. A host scopes the policy that admitted a config over that config’s run; a task spawned from fut must be wrapped again (current_reference_policy).