Struct Agent

Source

pub struct Agent { /* private fields */ }

Expand description

Agents provide redirects, connection pooling, cookies and retries.

Every request is sent through an agent, also when using the extension trait (Request.send()). When using the trait, the agent is intantiated with default parameters and lives for the length of the request.

To amend the default parameters, or reuse an agent over many requests, use Agent::new() and send the request using agent.send(req).

The default agent have the following settings:

Redirects: 5
Retries: 5
Connection pooling: on
Cookies: on

The settings can be changed, and are used for the next .send() call. It is possible to change the settings between calls.

use hreq::prelude::*;
use hreq::Agent;

let mut agent = Agent::new();
agent.retries(0); // disable all retries

let req = Request::get("https://httpbin.org/get")
    .with_body(()).unwrap();

let res = agent.send(req).block();

Implementations§

Source §

impl Agent

Source

pub fn new() -> Self

Creates a new agent with default parameters.

use hreq::Agent;

let agent = Agent::new();

Source

pub fn redirects(&mut self, amount: u8)

Changes number of redirects.

Defaults to 5. Set to 0 to disable redirects.

The number of redirects will be used for the next call to .send().

use hreq::Agent;

let mut agent = Agent::new();
agent.redirects(0);

Source

pub fn retries(&mut self, amount: u8)

Changes the number of retry attempts.

Defaults to 5. Set to 0 to disable retries.

The number of retries will be used for the next call to .send().

use hreq::Agent;

let mut agent = Agent::new();
agent.retries(0);

Source

pub fn pooling(&mut self, enabled: bool)

Turns connection pooling on or off.

Defaults to true. Set to false to disable connection pooling.

The setting will be used for the next call to .send().

When set to false any existing connection currently pooled will be dropped.

use hreq::Agent;

let mut agent = Agent::new();
agent.pooling(false);

Source

pub fn cookies(&mut self, enabled: bool)

Turns on or off the use of cookies.

Defaults to true. Set to false to disable use of cookies.

The setting will be used for the next call to .send().

When set to false, any previous collected cookie will be dropped.

use hreq::Agent;

let mut agent = Agent::new();
agent.cookies(false);

Source

pub fn get_cookies(&self, uri: &Uri) -> Vec<&Cookie<'static>>

Get all cookies held in this agent matching the given uri.

Source

pub async fn send<B: Into<Body>>( &mut self, req: Request, ) -> Result<Response<Body>, Error>

Sends a request using this agent.

The parameters configured in the agent are used for the request.

Depending on agent settings, connections are pooled and cookies reused between repeated calls to send().

use hreq::prelude::*;
use hreq::Agent;

let mut agent = Agent::new();
agent.retries(0);
agent.redirects(0);

let req = Request::get("https://fails-badly-yeah")
    .with_body(()).unwrap();

let res = agent.send(req).block();

assert!(res.is_err());
assert!(res.unwrap_err().is_io());