//!
//! //! //! Crates.io version //! //! //! //! docs.rs docs //! //! //! //! Crates.io downloads //! //!
//! //! A simple, safe HTTP client. //! //! Ureq's first priority is being easy for you to use. It's great for //! anyone who wants a low-overhead HTTP client that just gets the job done. Works //! very well with HTTP APIs. Its features include cookies, JSON, HTTP proxies, //! HTTPS, charset decoding, and is based on the API of the `http` crate. //! //! Ureq is in pure Rust for safety and ease of understanding. It forbids //! `unsafe` code. It uses blocking I/O instead of async I/O, because that keeps //! the API simple and keeps dependencies to a minimum. For TLS, ureq uses //! rustls or native-tls. //! //! See the [changelog] for details of recent releases. //! //! [changelog]: https://github.com/algesten/ureq/blob/main/CHANGELOG.md //! //! # Usage //! //! In its simplest form, ureq looks like this: //! //! ```rust //! let body: String = ureq::get("http://example.com") //! .header("Example-Header", "header value") //! .call()? //! .body_mut() //! .read_to_string()?; //! # Ok::<(), ureq::Error>(()) //! ``` //! //! For more involved tasks, you'll want to create an [`Agent`]. An Agent //! holds a connection pool for reuse, and a cookie store if you use the //! **cookies** feature. An Agent can be cheaply cloned due to internal //! [`Arc`] and all clones of an Agent share state among each other. Creating //! an Agent also allows setting options like the TLS configuration. //! //! ```rust //! # fn no_run() -> Result<(), ureq::Error> { //! use ureq::Agent; //! use std::time::Duration; //! //! let mut config = Agent::config_builder() //! .timeout_global(Some(Duration::from_secs(5))) //! .build(); //! //! let agent: Agent = config.into(); //! //! let body: String = agent.get("http://example.com/page") //! .call()? //! .body_mut() //! .read_to_string()?; //! //! // Reuses the connection from previous request. //! let response: String = agent.put("http://example.com/upload") //! .header("Authorization", "example-token") //! .send("some body data")? //! .body_mut() //! .read_to_string()?; //! # Ok(())} //! ``` //! //! ## Timeouts //! //! Configure timeouts on an [`Agent`] or override them per request through //! [`ConfigBuilder`]. Global, per-call, and phase timeouts //! measure total elapsed time. Each network operation uses the shortest applicable //! remaining budget. Per-read and per-write limits restart for each transport //! operation while the total budgets keep running. //! //! | Setting | Budget | //! | --- | --- | //! | `timeout_global` | Entire operation, including redirects and reading the response body. | //! | `timeout_per_call` | One HTTP exchange, including its body; reset for each redirect. | //! | `timeout_resolve` | Local target hostname resolution. | //! | `timeout_connect` | Proxy DNS, socket connection attempts, proxy negotiation, and TLS handshakes. | //! | `timeout_send_request` | Sending all request headers after connection setup. | //! | `timeout_await_100` | Waiting for `100 Continue` before uploading the body. | //! | `timeout_send_body` | Sending the entire request body. | //! | `timeout_recv_response` | Waiting for and receiving complete response headers. | //! | `timeout_recv_body` | Receiving the entire response body, starting after complete response headers. | //! | `timeout_per_read` | Each transport read, subject to the remaining total budgets. | //! | `timeout_per_write` | Each transport write, subject to the remaining total budgets. | //! //! A phase budget stops applying once that phase finishes. For example, a completed //! connection's `timeout_connect` does not limit the later response body transfer. //! A redirect starts new per-call and phase budgets while preserving the global //! budget. See the individual [`ConfigBuilder`] methods for //! protocol coverage and phase boundaries. //! //! Global, per-call, and response body budgets continue after a response is returned //! and while the application consumes its body. Time between body reads counts //! toward these budgets. Timeouts are checked during network I/O; they do not //! interrupt application code or a user-provided request body reader. //! //! `None` disables only that limit. All limits default to `None` except //! `timeout_await_100`, which defaults to one second. When that wait expires, ureq //! proceeds with the upload. Other timeouts are reported as [`Error::Timeout`], //! including through [`std::io::Error`] when using the body's [`std::io::Read`] API. //! //! ## JSON //! //! Ureq supports sending and receiving json, if you enable the **json** feature: //! //! ```rust //! # #[cfg(feature = "json")] //! # fn no_run() -> Result<(), ureq::Error> { //! use serde::{Serialize, Deserialize}; //! //! #[derive(Serialize)] //! struct MySendBody { //! thing: String, //! } //! //! #[derive(Deserialize)] //! struct MyRecvBody { //! other: String, //! } //! //! let send_body = MySendBody { thing: "yo".to_string() }; //! //! // Requires the `json` feature enabled. //! let recv_body = ureq::post("http://example.com/post/ingest") //! .header("X-My-Header", "Secret") //! .send_json(&send_body)? //! .body_mut() //! .read_json::()?; //! # Ok(())} //! ``` //! //! ## Error handling //! //! ureq returns errors via `Result`. That includes I/O errors, //! protocol errors. By default, also HTTP status code errors (when the //! server responded 4xx or 5xx) results in [`Error`]. //! //! This behavior can be turned off via [`http_status_as_error()`] //! //! ```rust //! use ureq::Error; //! //! # fn no_run() -> Result<(), 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 */ } //! } //! # Ok(())} //! ``` //! //! # Features //! //! To enable a minimal dependency tree, some features are off by default. //! You can control them when including ureq as a dependency. //! //! `ureq = { version = "3", features = ["socks-proxy", "charset"] }` //! //! The default enabled features are: **rustls** and **gzip**. //! //! * **rustls** enables the rustls TLS implementation. This is the default for the the crate level //! convenience calls (`ureq::get` etc). It currently uses `ring` as the TLS provider. //! * **native-tls** enables the native tls backend for TLS. Due to the risk of diamond dependencies //! accidentally switching on an unwanted TLS implementation, `native-tls` is never picked up as //! a default or used by the crate level convenience calls (`ureq::get` etc) – it must be configured //! on the agent //! * **platform-verifier** enables verifying the server certificates using a method native to the //! platform ureq is executing on. See [rustls-platform-verifier] crate //! * **socks-proxy** enables proxy config using the `socks4://`, `socks4a://`, `socks5://` //! and `socks://` (equal to `socks5://`) prefix //! * **cookies** enables cookies //! * **gzip** enables requests of gzip-compressed responses and decompresses them //! * **brotli** enables requests brotli-compressed responses and decompresses them //! * **charset** enables interpreting the charset part of the Content-Type header //! (e.g. `Content-Type: text/plain; charset=iso-8859-1`). Without this, the //! library defaults to Rust's built in `utf-8` //! * **json** enables JSON sending and receiving via serde_json //! * **multipart** enables multipart/form-data sending via [`unversioned::multipart`] //! * **rustls-webpki-roots** enables the webpki-roots crate for root certificates when using rustls. //! * **native-tls-webpki-roots** enables the webpki-root-certs crate for root certificates when using native-tls. //! //! ### Unstable //! //! These features are unstable and might change in a minor version. //! //! * **rustls-no-provider** Enables rustls, but does not enable webpki and any [`CryptoProvider`] such as `ring`. //! Root certs and providers other than the default (currently `ring`) are never picked up from feature flags alone. //! They must be configured on the agent. //! //! * **native-tls-no-default** Enables native-tls, but does not enable webpki. //! Root certs are never picked up from feature flags alone. They must be configured on the agent. //! //! * **vendored** compiles and statically links to a copy of non-Rust vendors (e.g. OpenSSL from `native-tls`) //! //! # TLS (https) //! //! ## rustls //! //! By default, ureq uses [`rustls` crate] with the `ring` cryptographic provider. //! As of Sep 2024, the `ring` provider has a higher chance of compiling successfully. If the user //! installs another process [default provider], that choice is respected. //! //! ureq does not guarantee to default to ring indefinitely. `rustls` as a feature flag will always //! work, but the specific crypto backend might change in a minor version. //! //! ``` //! # #[cfg(feature = "rustls")] //! # { //! // This uses rustls //! ureq::get("https://www.google.com/").call().unwrap(); //! # } Ok::<_, ureq::Error>(()) //! ``` //! //! ### rustls without ring //! //! ureq never changes TLS backend from feature flags alone. It is possible to compile ureq //! without ring, but it requires specific feature flags and configuring the [`Agent`]. //! //! Since rustls is not semver 1.x, this requires non-semver-guaranteed API. I.e. ureq might //! change this behavior without a major version bump. //! //! Read more at [`TlsConfigBuilder::unversioned_rustls_crypto_provider`][crate::tls::TlsConfigBuilder::unversioned_rustls_crypto_provider]. //! //! ## native-tls //! //! As an alternative, ureq ships with [`native-tls`] as a TLS provider. This must be //! enabled using the **native-tls** feature. Due to the risk of diamond dependencies //! accidentally switching on an unwanted TLS implementation, `native-tls` is never picked //! up as a default or used by the crate level convenience calls (`ureq::get` etc) – it //! must be configured on the agent. //! //! ``` //! # #[cfg(feature = "native-tls")] //! # { //! use ureq::config::Config; //! use ureq::tls::{TlsConfig, TlsProvider}; //! //! let mut config = Config::builder() //! .tls_config( //! TlsConfig::builder() //! // requires the native-tls feature //! .provider(TlsProvider::NativeTls) //! .build() //! ) //! .build(); //! //! let agent = config.new_agent(); //! //! agent.get("https://www.google.com/").call().unwrap(); //! # } Ok::<_, ureq::Error>(()) //! ``` //! //! ## Root certificates //! //! ### webpki-roots //! //! By default, ureq uses Mozilla's root certificates via the [webpki-roots] crate. This is a static //! bundle of root certificates that do not update automatically. It also circumvents whatever root //! certificates are installed on the host running ureq, which might be a good or a bad thing depending //! on your perspective. There is also no mechanism for [SCT], [CRL]s or other revocations. //! To maintain a "fresh" list of root certs, you need to bump the ureq dependency from time to time. //! //! The main reason for chosing this as the default is to minimize the number of dependencies. More //! details about this decision can be found at [PR 818]. //! //! If your use case for ureq is talking to a limited number of servers with high trust, the //! default setting is likely sufficient. If you use ureq with a high number of servers, or servers //! you don't trust, we recommend using the platform verifier (see below). //! //! ### platform-verifier //! //! The [rustls-platform-verifier] crate provides access to natively checking the certificate via your OS. //! To use this verifier, you need to enable it using feature flag **platform-verifier** as well as //! configure an agent to use it. //! //! ``` //! # #[cfg(all(feature = "rustls", feature="platform-verifier"))] //! # { //! use ureq::Agent; //! use ureq::tls::{TlsConfig, RootCerts}; //! //! let agent = Agent::config_builder() //! .tls_config( //! TlsConfig::builder() //! .root_certs(RootCerts::PlatformVerifier) //! .build() //! ) //! .build() //! .new_agent(); //! //! let response = agent.get("https://httpbin.org/get").call()?; //! # } Ok::<_, ureq::Error>(()) //! ``` //! //! Setting `RootCerts::PlatformVerifier` together with `TlsProvider::NativeTls` means //! also native-tls will use the OS roots instead of [webpki-roots] crate. Whether that //! results in a config that has CRLs and revocations is up to whatever native-tls links to. //! //! # JSON //! //! By enabling the **json** feature, the library supports serde json. //! //! This is disabled by default. //! //! * [`request.send_json()`] send body as json. //! * [`body.read_json()`] transform response to json. //! //! # Sending body data //! //! HTTP/1.1 has two ways of transfering body data. Either of a known size with //! the `Content-Length` HTTP header, or unknown size with the //! `Transfer-Encoding: chunked` header. ureq supports both and will use the //! appropriate method depending on which body is being sent. //! //! ureq has a [`AsSendBody`] trait that is implemented for many well known types //! of data that we might want to send. The request body can thus be anything //! from a `String` to a `File`, see below. //! //! ## Content-Length //! //! The library will send a `Content-Length` header on requests with bodies of //! known size, in other words, if the body to send is one of: //! //! * `&[u8]` //! * `&[u8; N]` //! * `&str` //! * `String` //! * `&String` //! * `Vec` //! * `&Vec)` //! * [`SendBody::from_json()`] (implicitly via [`request.send_json()`]) //! //! ## Transfer-Encoding: chunked //! //! ureq will send a `Transfer-Encoding: chunked` header on requests where the body //! is of unknown size. The body is automatically converted to an [`std::io::Read`] //! when the type is one of: //! //! * `File` //! * `&File` //! * `TcpStream` //! * `&TcpStream` //! * `Stdin` //! * `UnixStream` (not on windows) //! //! ### From readers //! //! The chunked method also applies for bodies constructed via: //! //! * [`SendBody::from_reader()`] //! * [`SendBody::from_owned_reader()`] //! //! ## Proxying a response body //! //! As a special case, when ureq sends a [`Body`] from a previous http call, the //! use of `Content-Length` or `chunked` depends on situation. For input such as //! gzip decoding (**gzip** feature) or charset transformation (**charset** feature), //! the output body might not match the input, which means ureq is forced to use //! the `chunked` method. //! //! * `Response` //! //! ## Sending form data //! //! [`request.send_form()`] provides a way to send `application/x-www-form-urlencoded` //! encoded data. The key/values provided will be URL encoded. //! //! ## Overriding //! //! If you set your own Content-Length or Transfer-Encoding header before //! sending the body, ureq will respect that header by not overriding it, //! and by encoding the body or not, as indicated by the headers you set. //! //! ``` //! let resp = ureq::put("https://httpbin.org/put") //! .header("Transfer-Encoding", "chunked") //! .send("Hello world")?; //! # Ok::<_, ureq::Error>(()) //! ``` //! //! # Character encoding //! //! By enabling the **charset** feature, the library supports receiving other //! character sets than `utf-8`. //! //! For [`Body::read_to_string()`] we read the header like: //! //! `Content-Type: text/plain; charset=iso-8859-1` //! //! and if it contains a charset specification, we try to decode the body using that //! encoding. In the absence of, or failing to interpret the charset, we fall back on `utf-8`. //! //! Currently ureq does not provide a way to encode when sending request bodies. //! //! ## Lossy utf-8 //! //! When reading text bodies (with a `Content-Type` starting `text/` as in `text/plain`, //! `text/html`, etc), ureq can ensure the body is possible to read as a `String` also if //! it contains characters that are not valid for utf-8. Invalid characters are replaced //! with a question mark `?` (NOT the utf-8 replacement character). //! //! For [`Body::read_to_string()`] this is turned on by default, but it can be disabled //! and conversely for [`Body::as_reader()`] it is not enabled, but can be. //! //! To precisely configure the behavior use [`Body::with_config()`]. //! //! # Proxying //! //! ureq supports two kinds of proxies, [`HTTP`] ([`CONNECT`]), [`SOCKS4`]/[`SOCKS5`], //! the former is always available while the latter must be enabled using the feature //! **socks-proxy**. //! //! Proxies settings are configured on an [`Agent`]. All request sent through the agent will be proxied. //! //! ## Environment Variables //! //! ureq automatically reads proxy configuration from environment variables when creating //! a default [`Agent`]. Proxy variables are checked in order: `ALL_PROXY`, `HTTPS_PROXY`, //! then `HTTP_PROXY` (with lowercase variants). //! //! `NO_PROXY` specifies hosts that bypass the proxy, supporting exact hosts, wildcard //! suffixes (`*.example.com`), dot suffixes (`.example.com`), and match-all (`*`). //! //! ## Example using HTTP //! //! ```rust //! use ureq::{Agent, Proxy}; //! # fn no_run() -> std::result::Result<(), ureq::Error> { //! // Configure an http connect proxy. //! let proxy = Proxy::new("http://user:password@cool.proxy:9090")?; //! let agent: Agent = Agent::config_builder() //! .proxy(Some(proxy)) //! .build() //! .into(); //! //! // This is proxied. //! let resp = agent.get("http://cool.server").call()?; //! # Ok(())} //! # fn main() {} //! ``` //! //! ## Example using SOCKS5 //! //! ```rust //! use ureq::{Agent, Proxy}; //! # #[cfg(feature = "socks-proxy")] //! # fn no_run() -> std::result::Result<(), ureq::Error> { //! // Configure a SOCKS proxy. //! let proxy = Proxy::new("socks5://user:password@cool.proxy:9090")?; //! let agent: Agent = Agent::config_builder() //! .proxy(Some(proxy)) //! .build() //! .into(); //! //! // This is proxied. //! let resp = agent.get("http://cool.server").call()?; //! # Ok(())} //! ``` //! //! # Log levels //! //! ureq uses the log crate. These are the definitions of the log levels, however we //! do not guarantee anything for dependencies such as `http` and `rustls`. //! //! * `ERROR` - nothing //! * `WARN` - if we detect a user configuration problem. //! * `INFO` - nothing //! * `DEBUG` - uri, state changes, transport, resolver and selected request/response headers //! * `TRACE` - wire level debug. NOT REDACTED! //! //! The request/response headers on DEBUG levels are allow-listed to only include headers that //! are considered safe. The code has the [allow list](https://github.com/algesten/ureq/blob/81127cfc38516903330dc1b9c618122372f8dc29/src/util.rs#L184-L198). //! //! # Versioning //! //! ## Semver and `unversioned` //! //! ureq follows semver. From ureq 3.x we strive to have a much closer adherence to semver than 2.x. //! The main mistake in 2.x was to re-export crates that were not yet semver 1.0. In ureq 3.x TLS and //! cookie configuration is shimmed using our own types. //! //! ureq 3.x is trying out two new traits that had no equivalent in 2.x, [`Transport`] and [`Resolver`]. //! These allow the user write their own bespoke transports and (DNS name) resolver. The API:s for //! these parts are not yet solidified. They live under the [`unversioned`] module, and do not //! follow semver. See module doc for more info. //! //! ## Breaking changes in dependencies //! //! ureq relies on non-semver 1.x crates such as `rustls` and `native-tls`. Some scenarios, such //! as configuring `rustls` to not use `ring`, a user of ureq might need to interact with these //! crates directly instead of going via ureq's provided API. //! //! Such changes can break when ureq updates dependencies. This is not considered a breaking change //! for ureq and will not be reflected by a major version bump. //! //! We strive to mark ureq's API with the word "unversioned" to identify places where this risk arises. //! //! ## Minimum Supported Rust Version (MSRV) //! //! From time to time we will need to update our minimum supported Rust version (MSRV). This is not //! something we do lightly; our ambition is to be as conservative with MSRV as possible. //! //! * For some dependencies, we will opt for pinning the version of the dep instead //! of bumping our MSRV. //! * For important dependencies, like the TLS libraries, we cannot hold back our MSRV if they change. //! * We do not consider MSRV changes to be breaking for the purposes of semver. //! * We will not make MSRV changes in patch releases. //! * MSRV changes will get their own minor release, and not be co-mingled with other changes. //! //! [`HTTP`]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Proxy_servers_and_tunneling#http_tunneling //! [`CONNECT`]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/CONNECT //! [`SOCKS4`]: https://en.wikipedia.org/wiki/SOCKS#SOCKS4 //! [`SOCKS5`]: https://en.wikipedia.org/wiki/SOCKS#SOCKS5 //! [`rustls` crate]: https://crates.io/crates/rustls //! [default provider]: https://docs.rs/rustls/latest/rustls/crypto/struct.CryptoProvider.html#method.install_default //! [`native-tls`]: https://crates.io/crates/native-tls //! [rustls-platform-verifier]: https://crates.io/crates/rustls-platform-verifier //! [webpki-roots]: https://crates.io/crates/webpki-roots //! [`Arc`]: https://doc.rust-lang.org/std/sync/struct.Arc.html //! [`Agent`]: https://docs.rs/ureq/latest/ureq/struct.Agent.html //! [`ConfigBuilder`]: https://docs.rs/ureq/latest/ureq/config/struct.ConfigBuilder.html //! [`Error`]: https://docs.rs/ureq/latest/ureq/enum.Error.html //! [`Error::Timeout`]: https://docs.rs/ureq/latest/ureq/enum.Error.html#variant.Timeout //! [`http_status_as_error()`]: https://docs.rs/ureq/latest/ureq/config/struct.ConfigBuilder.html#method.http_status_as_error //! [SCT]: https://en.wikipedia.org/wiki/Certificate_Transparency //! [CRL]: https://en.wikipedia.org/wiki/Certificate_revocation_list //! [PR 818]: https://github.com/algesten/ureq/pull/818 //! [`request.send_json()`]: https://docs.rs/ureq/latest/ureq/struct.RequestBuilder.html#method.send_json //! [`body.read_json()`]: https://docs.rs/ureq/latest/ureq/struct.Body.html#method.read_json //! [`AsSendBody`]: https://docs.rs/ureq/latest/ureq/trait.AsSendBody.html //! [`SendBody::from_json()`]: https://docs.rs/ureq/latest/ureq/struct.SendBody.html#method.from_json //! [`std::io::Read`]: https://doc.rust-lang.org/std/io/trait.Read.html //! [`std::io::Error`]: https://doc.rust-lang.org/std/io/struct.Error.html //! [`SendBody::from_reader()`]: https://docs.rs/ureq/latest/ureq/struct.SendBody.html#method.from_reader //! [`SendBody::from_owned_reader()`]: https://docs.rs/ureq/latest/ureq/struct.SendBody.html#method.from_owned_reader //! [`Body`]: https://docs.rs/ureq/latest/ureq/struct.Body.html //! [`request.send_form()`]: https://docs.rs/ureq/latest/ureq/struct.RequestBuilder.html#method.send_form //! [`Body::read_to_string()`]: https://docs.rs/ureq/latest/ureq/struct.Body.html#method.read_to_string //! [`Body::as_reader()`]: https://docs.rs/ureq/latest/ureq/struct.Body.html#method.as_reader //! [`Body::with_config()`]: https://docs.rs/ureq/latest/ureq/struct.Body.html#method.with_config //! [`Transport`]: https://docs.rs/ureq/latest/ureq/unversioned/transport/trait.Transport.html //! [`Resolver`]: https://docs.rs/ureq/latest/ureq/unversioned/resolver/trait.Resolver.html //! [`unversioned`]: https://docs.rs/ureq/latest/ureq/unversioned/index.html //! [`CryptoProvider`]: https://docs.rs/rustls/latest/rustls/crypto/struct.CryptoProvider.html //! [`unversioned::multipart`]: https://docs.rs/ureq/latest/ureq/unversioned/multipart/index.html #![forbid(unsafe_code)] #![warn(clippy::all)] #![deny(missing_docs)] // I don't think elided lifetimes help in understanding the code. #![allow(clippy::needless_lifetimes)] // Since you can't use inlined args for all cases, using it means the // code will have a mix of inlined and not inlined. Code should be // uniform, thus this lint is misguided. #![allow(clippy::uninlined_format_args)] // mismatched_lifetime_syntaxes was introduced after our MSRV. #![allow(unknown_lints, mismatched_lifetime_syntaxes)] #[macro_use] extern crate log; use std::convert::TryFrom; /// Re-exported http-crate. pub use ureq_proto::http; pub use body::{Body, BodyBuilder, BodyReader, BodyWithConfig}; use http::Method; use http::{Request, Response, Uri}; pub use proxy::{Proxy, ProxyBuilder, ProxyProtocol}; pub use request::RequestBuilder; use request::{WithBody, WithoutBody}; pub use request_ext::RequestExt; pub use response::ResponseExt; pub use send_body::AsSendBody; mod agent; mod body; pub mod config; mod error; mod pool; mod proxy; mod query; mod request; mod response; mod run; mod send_body; mod timings; mod util; pub mod unversioned; use unversioned::resolver; use unversioned::transport; pub mod middleware; #[cfg(feature = "_tls")] pub mod tls; #[cfg(feature = "cookies")] mod cookies; mod request_ext; #[cfg(feature = "cookies")] pub use cookies::{Cookie, CookieJar}; pub use agent::Agent; pub use error::Error; pub use send_body::SendBody; pub use timings::Timeout; /// Typestate variables. pub mod typestate { pub use super::request::WithBody; pub use super::request::WithoutBody; pub use super::config::typestate::AgentScope; pub use super::config::typestate::HttpCrateScope; pub use super::config::typestate::RequestScope; } /// Run a [`http::Request`]. pub fn run(request: Request) -> Result, Error> { let agent = Agent::new_with_defaults(); agent.run(request) } /// A new [Agent] with default configuration /// /// Agents are used to hold configuration and keep state between requests. pub fn agent() -> Agent { Agent::new_with_defaults() } /// Make a GET request. /// /// Run on a use-once [`Agent`]. #[must_use] pub fn get(uri: T) -> RequestBuilder where Uri: TryFrom, >::Error: Into, { RequestBuilder::::new(Agent::new_with_defaults(), Method::GET, uri) } /// Make a POST request. /// /// Run on a use-once [`Agent`]. #[must_use] pub fn post(uri: T) -> RequestBuilder where Uri: TryFrom, >::Error: Into, { RequestBuilder::::new(Agent::new_with_defaults(), Method::POST, uri) } /// Make a PUT request. /// /// Run on a use-once [`Agent`]. #[must_use] pub fn put(uri: T) -> RequestBuilder where Uri: TryFrom, >::Error: Into, { RequestBuilder::::new(Agent::new_with_defaults(), Method::PUT, uri) } /// Make a DELETE request. /// /// Run on a use-once [`Agent`]. #[must_use] pub fn delete(uri: T) -> RequestBuilder where Uri: TryFrom, >::Error: Into, { RequestBuilder::::new(Agent::new_with_defaults(), Method::DELETE, uri) } /// Make a HEAD request. /// /// Run on a use-once [`Agent`]. #[must_use] pub fn head(uri: T) -> RequestBuilder where Uri: TryFrom, >::Error: Into, { RequestBuilder::::new(Agent::new_with_defaults(), Method::HEAD, uri) } /// Make an OPTIONS request. /// /// Run on a use-once [`Agent`]. #[must_use] pub fn options(uri: T) -> RequestBuilder where Uri: TryFrom, >::Error: Into, { RequestBuilder::::new(Agent::new_with_defaults(), Method::OPTIONS, uri) } /// Make a CONNECT request. /// /// Run on a use-once [`Agent`]. #[must_use] pub fn connect(uri: T) -> RequestBuilder where Uri: TryFrom, >::Error: Into, { RequestBuilder::::new(Agent::new_with_defaults(), Method::CONNECT, uri) } /// Make a PATCH request. /// /// Run on a use-once [`Agent`]. #[must_use] pub fn patch(uri: T) -> RequestBuilder where Uri: TryFrom, >::Error: Into, { RequestBuilder::::new(Agent::new_with_defaults(), Method::PATCH, uri) } /// Make a TRACE request. /// /// Run on a use-once [`Agent`]. #[must_use] pub fn trace(uri: T) -> RequestBuilder where Uri: TryFrom, >::Error: Into, { RequestBuilder::::new(Agent::new_with_defaults(), Method::TRACE, uri) } #[cfg(test)] pub(crate) mod test { use std::{io, sync::OnceLock}; use assert_no_alloc::AllocDisabler; use config::{Config, ConfigBuilder}; use typestate::AgentScope; use super::*; #[global_allocator] // Some tests checks that we are not allocating static A: AllocDisabler = AllocDisabler; pub fn init_test_log() { static INIT_LOG: OnceLock<()> = OnceLock::new(); INIT_LOG.get_or_init(env_logger::init); } #[test] fn connect_http_google() { init_test_log(); let agent = Agent::new_with_defaults(); let res = agent.get("http://www.google.com/").call().unwrap(); assert_eq!( "text/html;charset=ISO-8859-1", res.headers() .get("content-type") .unwrap() .to_str() .unwrap() .replace("; ", ";") ); assert_eq!(res.body().mime_type(), Some("text/html")); } #[test] #[cfg(feature = "rustls")] fn connect_https_google_rustls() { init_test_log(); use config::Config; use crate::tls::{TlsConfig, TlsProvider}; let agent: Agent = Config::builder() .tls_config(TlsConfig::builder().provider(TlsProvider::Rustls).build()) .build() .into(); let res = agent.get("https://www.google.com/").call().unwrap(); assert_eq!( "text/html;charset=ISO-8859-1", res.headers() .get("content-type") .unwrap() .to_str() .unwrap() .replace("; ", ";") ); assert_eq!(res.body().mime_type(), Some("text/html")); } #[test] #[cfg(feature = "native-tls")] fn connect_https_google_native_tls_simple() { init_test_log(); use config::Config; use crate::tls::{TlsConfig, TlsProvider}; let agent: Agent = Config::builder() .tls_config( TlsConfig::builder() .provider(TlsProvider::NativeTls) .build(), ) .build() .into(); let mut res = agent.get("https://www.google.com/").call().unwrap(); assert_eq!( "text/html;charset=ISO-8859-1", res.headers() .get("content-type") .unwrap() .to_str() .unwrap() .replace("; ", ";") ); assert_eq!(res.body().mime_type(), Some("text/html")); res.body_mut().read_to_string().unwrap(); } #[test] #[cfg(feature = "rustls")] fn connect_https_google_rustls_webpki() { init_test_log(); use crate::tls::{RootCerts, TlsConfig, TlsProvider}; use config::Config; let agent: Agent = Config::builder() .tls_config( TlsConfig::builder() .provider(TlsProvider::Rustls) .root_certs(RootCerts::WebPki) .build(), ) .build() .into(); agent.get("https://www.google.com/").call().unwrap(); } #[test] #[cfg(feature = "native-tls")] fn connect_https_google_native_tls_webpki() { init_test_log(); use crate::tls::{RootCerts, TlsConfig, TlsProvider}; use config::Config; let agent: Agent = Config::builder() .tls_config( TlsConfig::builder() .provider(TlsProvider::NativeTls) .root_certs(RootCerts::WebPki) .build(), ) .build() .into(); agent.get("https://www.google.com/").call().unwrap(); } #[test] #[cfg(feature = "rustls")] fn connect_https_google_noverif() { init_test_log(); use crate::tls::{TlsConfig, TlsProvider}; let agent: Agent = Config::builder() .tls_config( TlsConfig::builder() .provider(TlsProvider::Rustls) .disable_verification(true) .build(), ) .build() .into(); let res = agent.get("https://www.google.com/").call().unwrap(); assert_eq!( "text/html;charset=ISO-8859-1", res.headers() .get("content-type") .unwrap() .to_str() .unwrap() .replace("; ", ";") ); assert_eq!(res.body().mime_type(), Some("text/html")); } #[test] fn simple_put_content_len() { init_test_log(); let mut res = put("http://httpbin.org/put").send(&[0_u8; 100]).unwrap(); res.body_mut().read_to_string().unwrap(); } #[test] fn simple_put_chunked() { init_test_log(); let mut res = put("http://httpbin.org/put") // override default behavior .header("transfer-encoding", "chunked") .send(&[0_u8; 100]) .unwrap(); res.body_mut().read_to_string().unwrap(); } #[test] fn simple_get() { init_test_log(); let mut res = get("http://httpbin.org/get").call().unwrap(); res.body_mut().read_to_string().unwrap(); } #[test] fn query_no_slash() { init_test_log(); let mut res = get("http://httpbin.org?query=foo").call().unwrap(); res.body_mut().read_to_string().unwrap(); } #[test] fn simple_head() { init_test_log(); let mut res = head("http://httpbin.org/get").call().unwrap(); res.body_mut().read_to_string().unwrap(); } #[test] fn redirect_no_follow() { init_test_log(); let agent: Agent = Config::builder().max_redirects(0).build().into(); let mut res = agent .get("http://httpbin.org/redirect-to?url=%2Fget") .call() .unwrap(); let txt = res.body_mut().read_to_string().unwrap(); #[cfg(feature = "_test")] assert_eq!(txt, "You've been redirected"); #[cfg(not(feature = "_test"))] assert_eq!(txt, ""); } #[test] fn test_send_form_content_type() { init_test_log(); // These tests verify that the methods work correctly with the test infrastructure // The actual Content-Type verification happens at the transport level let form_data = [("key1", "value1"), ("key2", "value2")]; let mut res = post("http://httpbin.org/post") .header("x-verify-content-type", "application/x-www-form-urlencoded") .send_form(form_data) .unwrap(); let _txt = res.body_mut().read_to_string().unwrap(); } #[test] #[cfg(feature = "json")] fn test_send_json_content_type() { use serde_json::json; init_test_log(); let data = json!({"key": "value"}); let mut res = post("http://httpbin.org/post") .header("x-verify-content-type", "application/json; charset=utf-8") .send_json(&data) .unwrap(); let _txt = res.body_mut().read_to_string().unwrap(); } #[test] #[cfg(feature = "multipart")] fn test_send_multipart_content_type() { use crate::unversioned::multipart::Form; init_test_log(); let form = Form::new() .text("field1", "value1") .text("field2", "value2"); let mut res = post("http://httpbin.org/post") .header("x-verify-content-type", "multipart/form-data") .send(form) .unwrap(); let _txt = res.body_mut().read_to_string().unwrap(); } #[test] fn redirect_max_with_error() { init_test_log(); let agent: Agent = Config::builder().max_redirects(3).build().into(); let res = agent .get( "http://httpbin.org/redirect-to?url=%2Fredirect-to%3F\ url%3D%2Fredirect-to%3Furl%3D%252Fredirect-to%253Furl%253D", ) .call(); let err = res.unwrap_err(); assert_eq!(err.to_string(), "too many redirects"); } #[test] fn redirect_max_without_error() { init_test_log(); let agent: Agent = Config::builder() .max_redirects(3) .max_redirects_will_error(false) .build() .into(); let res = agent .get( "http://httpbin.org/redirect-to?url=%2Fredirect-to%3F\ url%3D%2Fredirect-to%3Furl%3D%252Fredirect-to%253Furl%253D", ) .call() .unwrap(); assert_eq!(res.status(), 302); } #[test] fn redirect_follow() { init_test_log(); let res = get("http://httpbin.org/redirect-to?url=%2Fget") .call() .unwrap(); let response_uri = res.get_uri(); assert_eq!(response_uri.path(), "/get") } #[test] #[cfg(feature = "_test")] fn post_redirect_to_get_removes_content_length() { // Regression test for issue #1135 // When a POST with body redirects to GET, Content-Length should not be sent use crate::transport::{set_handler, set_handler_cb}; init_test_log(); // POST endpoint that redirects to GET set_handler( "/post-redirect", 301, &[("Location", "http://example.com/get")], &[], ); // GET endpoint - verifies Content-Length header is NOT present set_handler_cb("/get", 200, &[], b"success", |req| { // Assert that Content-Length is not present on the GET request assert!( req.headers().get("content-length").is_none(), "Content-Length header should not be present on GET request after redirect" ); }); // POST with body that redirects to GET let mut res = post("http://example.org/post-redirect") .send("test body") .unwrap(); assert_eq!(res.status(), 200); let body = res.body_mut().read_to_string().unwrap(); assert_eq!(body, "success"); } #[test] fn redirect_history_none() { init_test_log(); let res = get("http://httpbin.org/redirect-to?url=%2Fget") .call() .unwrap(); let redirect_history = res.get_redirect_history(); assert_eq!(redirect_history, None) } #[test] fn redirect_history_some() { init_test_log(); let agent: Agent = Config::builder() .max_redirects(3) .max_redirects_will_error(false) .save_redirect_history(true) .build() .into(); let res = agent .get("http://httpbin.org/redirect-to?url=%2Fget") .call() .unwrap(); let redirect_history = res.get_redirect_history(); assert_eq!( redirect_history, Some( vec![ "http://httpbin.org/redirect-to?url=%2Fget".parse().unwrap(), "http://httpbin.org/get".parse().unwrap() ] .as_ref() ) ); let res = agent .get( "http://httpbin.org/redirect-to?url=%2Fredirect-to%3F\ url%3D%2Fredirect-to%3Furl%3D%252Fredirect-to%253Furl%253D", ) .call() .unwrap(); let redirect_history = res.get_redirect_history(); assert_eq!( redirect_history, Some(vec![ "http://httpbin.org/redirect-to?url=%2Fredirect-to%3Furl%3D%2Fredirect-to%3Furl%3D%252Fredirect-to%253Furl%253D".parse().unwrap(), "http://httpbin.org/redirect-to?url=/redirect-to?url=%2Fredirect-to%3Furl%3D".parse().unwrap(), "http://httpbin.org/redirect-to?url=/redirect-to?url=".parse().unwrap(), "http://httpbin.org/redirect-to?url=".parse().unwrap(), ].as_ref()) ); let res = agent.get("https://www.google.com/").call().unwrap(); let redirect_history = res.get_redirect_history(); assert_eq!( redirect_history, Some(vec!["https://www.google.com/".parse().unwrap()].as_ref()) ); } #[test] fn connect_https_invalid_name() { let result = get("https://example.com{REQUEST_URI}/").call(); let err = result.unwrap_err(); assert!(matches!(err, Error::Http(_))); assert_eq!(err.to_string(), "http: invalid uri character"); } #[test] fn post_big_body_chunked() { init_test_log(); // https://github.com/algesten/ureq/issues/879 let mut data = io::Cursor::new(vec![42; 153_600]); post("http://httpbin.org/post") .content_type("application/octet-stream") .send(SendBody::from_reader(&mut data)) .expect("to send correctly"); } #[test] #[cfg(not(feature = "_test"))] fn post_array_body_sends_content_length() { init_test_log(); let mut response = post("http://httpbin.org/post") .content_type("application/octet-stream") .send(vec![42; 123]) .expect("to send correctly"); let ret = response.body_mut().read_to_string().unwrap(); assert!(ret.contains("\"Content-Length\": \"123\"")); } #[test] #[cfg(not(feature = "_test"))] fn post_file_sends_file_length() { init_test_log(); let bytes = include_bytes!("../LICENSE-MIT"); let file = std::fs::File::open("LICENSE-MIT").unwrap(); let mut response = post("http://httpbin.org/post") .content_type("application/octet-stream") .send(file) .expect("to send correctly"); let ret = response.body_mut().read_to_string().unwrap(); assert!(ret.contains(&format!("\"Content-Length\": \"{}\"", bytes.len()))); } #[test] #[cfg(not(feature = "_test"))] fn username_password_from_uri() { init_test_log(); let mut res = get("https://martin:secret@httpbin.org/get").call().unwrap(); let body = res.body_mut().read_to_string().unwrap(); assert!(body.contains("Basic bWFydGluOnNlY3JldA==")); } #[test] #[cfg(all(feature = "cookies", feature = "_test"))] fn store_response_cookies() { let agent = Agent::new_with_defaults(); let _ = agent.get("https://www.google.com").call().unwrap(); let mut all: Vec<_> = agent .cookie_jar_lock() .iter() .map(|c| c.name().to_string()) .collect(); all.sort(); assert_eq!(all, ["AEC", "__Secure-ENID"]) } #[test] #[cfg(all(feature = "cookies", feature = "_test"))] fn send_request_cookies() { init_test_log(); let agent = Agent::new_with_defaults(); let uri = Uri::from_static("http://cookie.test/cookie-test"); let uri2 = Uri::from_static("http://cookie2.test/cookie-test"); let mut jar = agent.cookie_jar_lock(); jar.insert(Cookie::parse("a=1", &uri).unwrap(), &uri) .unwrap(); jar.insert(Cookie::parse("b=2", &uri).unwrap(), &uri) .unwrap(); jar.insert(Cookie::parse("c=3", &uri2).unwrap(), &uri2) .unwrap(); jar.release(); let _ = agent.get("http://cookie.test/cookie-test").call().unwrap(); } #[test] #[cfg(all(feature = "_test", not(feature = "cookies")))] fn partial_redirect_when_following() { init_test_log(); // this should work because we follow the redirect and go to /get get("http://my-host.com/partial-redirect").call().unwrap(); } #[test] #[cfg(feature = "_test")] fn partial_redirect_when_not_following() { init_test_log(); // this should fail because we are not following redirects, and the // response is partial before the server is hanging up get("http://my-host.com/partial-redirect") .config() .max_redirects(0) .build() .call() .unwrap_err(); } #[test] #[cfg(feature = "_test")] fn http_connect_proxy() { init_test_log(); let proxy = Proxy::new("http://my_proxy:1234/connect-proxy").unwrap(); let agent = Agent::config_builder() .proxy(Some(proxy)) .build() .new_agent(); let mut res = agent.get("http://httpbin.org/get").call().unwrap(); res.body_mut().read_to_string().unwrap(); } #[test] #[cfg(all(feature = "_test", feature = "_ring"))] fn https_connect_proxy_to_https_target() { init_test_log(); for provider in [ tls::TlsProvider::Rustls, #[cfg(feature = "native-tls-no-default")] tls::TlsProvider::NativeTls, ] { let proxy = Proxy::new("https://proxy.test/https-connect-proxy").unwrap(); let tls = tls::TlsConfig::builder() .provider(provider) .disable_verification(true) .build(); let agent = Agent::config_builder() .proxy(Some(proxy)) .tls_config(tls) .build() .new_agent(); let mut response = agent .get("https://example.com/through-https-proxy") .call() .unwrap(); assert_eq!(response.body_mut().read_to_string().unwrap(), "ok"); } } #[test] fn ensure_reasonable_stack_sizes() { macro_rules! ensure { ($type:ty, $size:tt) => { let sz = std::mem::size_of::<$type>(); // println!("{}: {}", stringify!($type), sz); assert!( sz <= $size, "Stack size of {} is too big {} > {}", stringify!($type), sz, $size ); }; } ensure!(RequestBuilder, 400); // 304 ensure!(Agent, 100); // 32 ensure!(Config, 400); // 320 ensure!(ConfigBuilder, 400); // 320 ensure!(Response, 250); // 136 ensure!(Body, 50); // 24 } #[test] #[cfg(feature = "_test")] fn limit_max_response_header_size() { init_test_log(); let err = get("http://httpbin.org/get") .config() .max_response_header_size(5) .build() .call() .unwrap_err(); assert!(matches!(err, Error::LargeResponseHeader(65, 5))); } #[test] #[cfg(feature = "_test")] fn propfind_with_body() { init_test_log(); // https://github.com/algesten/ureq/issues/1034 let request = http::Request::builder() .method("PROPFIND") .uri("https://www.google.com/") .body("Some really cool body") .unwrap(); let _ = Agent::config_builder() .allow_non_standard_methods(true) .build() .new_agent() .run(request) .unwrap(); } #[test] #[cfg(feature = "_test")] fn non_standard_method() { init_test_log(); let method = Method::from_bytes(b"FNORD").unwrap(); let req = Request::builder() .method(method) .uri("http://httpbin.org/fnord") .body(()) .unwrap(); let agent = Agent::new_with_defaults(); let req = agent .configure_request(req) .allow_non_standard_methods(true) .build(); agent.run(req).unwrap(); } #[test] #[cfg(feature = "_test")] fn chunk_abort() { init_test_log(); let mut res = get("http://my-fine-server/1chunk-abort").call().unwrap(); let body = res.body_mut().read_to_string().unwrap(); assert_eq!(body, "OK"); let mut res = get("http://my-fine-server/2chunk-abort").call().unwrap(); let body = res.body_mut().read_to_string().unwrap(); assert_eq!(body, "OK"); let mut res = get("http://my-fine-server/3chunk-abort").call().unwrap(); let body = res.body_mut().read_to_string().unwrap(); assert_eq!(body, "OK"); let mut res = get("http://my-fine-server/4chunk-abort").call().unwrap(); let body = res.body_mut().read_to_string().unwrap(); assert_eq!(body, "OK"); } // This doesn't need to run, just compile. fn _ensure_send_sync() { fn is_send(_t: impl Send) {} fn is_sync(_t: impl Sync) {} // Agent is_send(Agent::new_with_defaults()); is_sync(Agent::new_with_defaults()); // ResponseBuilder is_send(get("https://example.test")); is_sync(get("https://example.test")); let data = vec![0_u8, 1, 2, 3, 4]; // Response via ResponseBuilder is_send(post("https://example.test").send(&data)); is_sync(post("https://example.test").send(&data)); // Request is_send(Request::post("https://yaz").body(&data).unwrap()); is_sync(Request::post("https://yaz").body(&data).unwrap()); // Response via Agent::run is_send(run(Request::post("https://yaz").body(&data).unwrap())); is_sync(run(Request::post("https://yaz").body(&data).unwrap())); // Response> let mut response = post("https://yaz").send(&data).unwrap(); let shared_reader = response.body_mut().as_reader(); is_send(shared_reader); let shared_reader = response.body_mut().as_reader(); is_sync(shared_reader); // Response> let response = post("https://yaz").send(&data).unwrap(); let owned_reader = response.into_parts().1.into_reader(); is_send(owned_reader); let response = post("https://yaz").send(&data).unwrap(); let owned_reader = response.into_parts().1.into_reader(); is_sync(owned_reader); let err = Error::HostNotFound; is_send(err); let err = Error::HostNotFound; is_sync(err); } } #[cfg(test)] mod io_timeout_tests; #[cfg(test)] mod shutdown_tests;