Struct ureq::Agent

pub struct Agent { /* fields omitted */ }

Agents keep state between requests.

By default, no state, such as cookies, is kept between requests. But by creating an agent as entry point for the request, we can keep a state.

let agent = ureq::agent();

let auth = agent
    .post("/login")
    .auth("martin", "rubbermashgum")
    .call(); // blocks. puts auth cookies in agent.

if !auth.ok() {
    println!("Noes!");
}

let secret = agent
    .get("/my-protected-page")
    .call(); // blocks and waits for request.

if !secret.ok() {
    println!("Wot?!");
}

println!("Secret is: {}", secret.into_string().unwrap());

Implementations

impl Agent

pub fn new() -> Agent

Creates a new agent. Typically you’d use ureq::agent() to do this.

let agent = ureq::Agent::new()
    .set("X-My-Header", "Foo") // present on all requests from this agent
    .build();

agent.get("/foo");

pub fn build(&self) -> Self

Create a new agent after treating it as a builder. This actually clones the internal state to a new one and instantiates a new connection pool that is reused between connects.

pub fn set(&mut self, header: &str, value: &str) -> &mut Agent

Set a header field that will be present in all requests using the agent.

let agent = ureq::agent()
    .set("X-API-Key", "foobar")
    .set("Accept", "text/plain")
    .build();

let r = agent
    .get("/my-page")
    .call();

 if r.ok() {
     println!("yay got {}", r.into_string().unwrap());
 } else {
     println!("Oh no error!");
 }

pub fn auth(&mut self, user: &str, pass: &str) -> &mut Agent

Basic auth that will be present in all requests using the agent.

let agent = ureq::agent()
    .auth("martin", "rubbermashgum")
    .build();

let r = agent
    .get("/my_page")
    .call();
println!("{:?}", r);

pub fn auth_kind(&mut self, kind: &str, pass: &str) -> &mut Agent

Auth of other kinds such as Digest, Token etc, that will be present in all requests using the agent.

// sets a header "Authorization: token secret"
let agent = ureq::agent()
    .auth_kind("token", "secret")
    .build();

let r = agent
    .get("/my_page")
    .call();

pub fn request(&self, method: &str, path: &str) -> Request

Request by providing the HTTP verb such as GET, POST…

let agent = ureq::agent();

let r = agent
    .request("GET", "/my_page")
    .call();
println!("{:?}", r);

pub fn set_max_pool_connections(&self, max_connections: usize)

Sets the maximum number of connections allowed in the connection pool. By default, this is set to 100. Setting this to zero would disable connection pooling.

let agent = ureq::agent();
agent.set_max_pool_connections(200);

pub fn set_max_pool_connections_per_host(&self, max_connections: usize)

Sets the maximum number of connections per host to keep in the connection pool. By default, this is set to 1. Setting this to zero would disable connection pooling.

let agent = ureq::agent();
agent.set_max_pool_connections_per_host(10);

pub fn set_resolver(&mut self, resolver: impl Resolver + 'static) -> &mut Self

Configures a custom resolver to be used by this agent. By default, address-resolution is done by std::net::ToSocketAddrs. This allows you to override that resolution with your own alternative. Useful for testing and special-cases like DNS-based load balancing.

A Fn(&str) -> io::Result<Vec<SocketAddr>> is a valid resolver, passing a closure is a simple way to override. Note that you might need explicit type &str on the closure argument for type inference to succeed.

use std::net::ToSocketAddrs;

let mut agent = ureq::agent();
agent.set_resolver(|addr: &str| match addr {
   "example.com" => Ok(vec![([127,0,0,1], 8096).into()]),
   addr => addr.to_socket_addrs().map(Iterator::collect),
});

pub fn set_proxy(&mut self, proxy: Proxy) -> &mut Agent

Set the proxy server to use for all connections from this Agent.

Example:

let proxy = ureq::Proxy::new("user:password@cool.proxy:9090").unwrap();
let agent = ureq::agent()
    .set_proxy(proxy)
    .build();

pub fn cookie(&self, name: &str) -> Option<Cookie<'static>>

Gets a cookie in this agent by name. Cookies are available either by setting it in the agent, or by making requests that Set-Cookie in the agent.

Note that this will return any cookie for the given name, regardless of which host and path that cookie was set on.

let agent = ureq::agent();

agent.get("http://www.google.com").call();

assert!(agent.cookie("NID").is_some());

pub fn set_cookie(&self, cookie: Cookie<'static>)

Set a cookie in this agent.

Cookies without a domain, or with a malformed domain or path, will be silently ignored.

let agent = ureq::agent();

let cookie = ureq::Cookie::build("name", "value")
  .domain("example.com")
  .path("/")
  .secure(true)
  .finish();
agent.set_cookie(cookie);

pub fn get(&self, path: &str) -> Request

Make a GET request from this agent.

pub fn head(&self, path: &str) -> Request

Make a HEAD request from this agent.

pub fn post(&self, path: &str) -> Request

Make a POST request from this agent.

pub fn put(&self, path: &str) -> Request

Make a PUT request from this agent.

pub fn delete(&self, path: &str) -> Request

Make a DELETE request from this agent.

pub fn trace(&self, path: &str) -> Request

Make a TRACE request from this agent.

pub fn options(&self, path: &str) -> Request

Make a OPTIONS request from this agent.

pub fn patch(&self, path: &str) -> Request

Make a PATCH request from this agent.

Trait Implementations

impl Clone for Agent

fn clone(&self) -> Agent

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Agent

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Agent

fn default() -> Agent

Returns the “default value” for a type.