Awesome
!!! main branch is ureq 3.x !!!
In anticipation of releasig ureq 3.x, the main branch is now the 3.x version. The current main released version is in the 2.x branch.
ureq
<div align="center"> <!-- Version --> <a href="https://crates.io/crates/ureq"> <img src="https://img.shields.io/crates/v/ureq.svg?style=flat-square" alt="Crates.io version" /> </a> <!-- Docs --> <a href="https://docs.rs/ureq"> <img src="https://img.shields.io/badge/docs-latest-blue.svg?style=flat-square" alt="docs.rs docs" /> </a> <!-- Downloads --> <a href="https://crates.io/crates/ureq"> <img src="https://img.shields.io/crates/d/ureq.svg?style=flat-square" alt="Crates.io downloads" /> </a> </div>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, interoperability with the http
crate, and charset decoding.
Ureq is in pure Rust for safety and ease of understanding. It avoids using
unsafe
directly. 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.
Usage
In its simplest form, ureq looks like this:
let body: String = ureq::get("http://example.com")
.header("Example-Header", "header value")
.call()?
.body_mut()
.read_to_string()?;
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.
use ureq::{Agent, AgentConfig};
use std::time::Duration;
let agent: Agent = AgentConfig {
timeout_global: Some(Duration::from_secs(5)),
..Default::default()
}.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()?;
JSON
Ureq supports sending and receiving json, if you enable the json feature:
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::<MyRecvBody>()?;
Error handling
ureq returns errors via Result<T, ureq::Error>
. 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 [AgentConfig::http_status_as_error
].
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 */ }
}
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, gzip and json.
- rustls enabled the rustls TLS implementation. This is the defeault for the the crate level
convenience calls (
ureq::get
etc). - 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. - socks-proxy enables proxy config using the
socks4://
,socks4a://
,socks5://
andsocks://
(equal tosocks5://
) 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 inutf-8
. - json enables JSON sending and receiving via serde_json.
JSON
By enabling the json feature, the library supports serde json.
This is enabled by default.
- [
request.send_json()
][RequestBuilder::send_json()] send body as json. - [
body.read_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<u8>
&Vec<u8>)
- [
SendBody::from_json()
] (implicitly via [RequestBuilder::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<Body>
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")?;
Character encoding
By enabling the charset feature, the library supports sending/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
.
Similarly when using [request.send()
][RequestBuilder::send()] with a text body,
we first check if the user has set a ; charset=<whatwg charset>
and attempt
to encode the request body using that.
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.
Example using HTTP
use ureq::{Agent, AgentConfig, Proxy};
// Configure an http connect proxy.
let proxy = Proxy::new("http://user:password@cool.proxy:9090")?;
let agent: Agent = AgentConfig {
proxy: Some(proxy),
..Default::default()
}.into();
// This is proxied.
let resp = agent.get("http://cool.server").call()?;
Example using SOCKS5
use ureq::{Agent, AgentConfig, Proxy};
// Configure a SOCKS proxy.
let proxy = Proxy::new("socks5://user:password@cool.proxy:9090")?;
let agent: Agent = AgentConfig {
proxy: Some(proxy),
..Default::default()
}.into();
// This is proxied.
let resp = agent.get("http://cool.server").call()?;