devela::_dep::ureq

Struct Agent

Help

pub struct Agent { /* private fields */ }

Available on crate feature dep_ureq only.

Expand description

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.

§Example

let mut agent = ureq::agent();

agent
    .post("http://example.com/post/login")
    .send(b"my password")?;

let secret = agent
    .get("http://example.com/get/my-protected-page")
    .call()?
    .body_mut()
    .read_to_string()?;

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

§About threads and cloning

Agent uses inner Arc. Cloning an Agent results in an instance that shares the same underlying connection pool and other state.

The connection pool contains an inner Mutex which is (briefly) held when borrowing a pooled connection, or returning a connection to the pool.

All request functions in ureq have a signature similar to this:

fn run(request: http::Request<impl AsSendBody>) -> Result<http::Response<Body>, Error> {
    // <something>
}

It follows that:

An Agent is borrowed for the duration of:
1. Sending the request header (http::Request)
2. Sending the request body (SendBody)
3. Receiving the response header (http::Response)
The Body of the response is not bound to the lifetime of the Agent.

A response Body can be streamed (for instance via Body::into_reader()). The Body implements Send, which means it’s possible to read the response body on another thread than the one that run the request. Behind the scenes, the Body retains the connection to the remote server and it is returned to the agent’s pool, once the Body instance (or reader) is dropped.

There is an asymmetry in that sending a request body will borrow the Agent instance, while receiving the response body does not. This inconvencience is somewhat mitigated by that Agent::run() (or going via the methods such as Agent::get()), borrows &self, i.e. not exclusive mut borrows.

That cloning the agent shares the connection pool is considered a feature. It is often useful to retain a single pool for the entire process, while dispatching requests from different threads. And if we want separate pools, we can create multiple agents via one of the constructors (such as Agent::new_with_config()).

Note that both Config::clone() and Agent::clone() are “cheap” meaning they should not incur any heap allocation.

Implementations§

§

impl Agent

pub fn new_with_defaults() -> Agent

Creates an agent with defaults.

pub fn new_with_config(config: Config) -> Agent

Creates an agent with config.

pub fn config_builder() -> ConfigBuilder<AgentScope>

Shortcut to reach a ConfigBuilder

This is the same as doing Config::builder().

pub fn with_parts( config: Config, connector: impl Connector, resolver: impl Resolver, ) -> Agent

Creates an agent with a bespoke transport and resolver.

This is low level API that isn’t for regular use of ureq.

pub fn run( &self, request: Request<impl AsSendBody>, ) -> Result<Response<Body>, Error> ⓘ

Run a http::Request<impl AsSendBody>.

Used to execute http crate http::Request directly on this agent.

§Example

use ureq::{http, Agent};

let agent: Agent = Agent::new_with_defaults();

let mut request =
    http::Request::get("http://httpbin.org/get")
    .body(())?;

let body = agent.run(request)?
    .body_mut()
    .read_to_string()?;

pub fn config(&self) -> &Config

Get the config for this agent.

pub fn configure_request<S>( &self, request: Request<S>, ) -> ConfigBuilder<HttpCrateScope<S>>
where S: AsSendBody,

Alter the configuration for an http crate request.

Notice: It’s an error to configure a http::Request using one instance of Agent and run using another instance. The library does not currently detect this situation, but it is not considered a breaking change if this is enforced in the future.

pub fn get<T>(&self, uri: T) -> RequestBuilder<WithoutBody>
where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

Make a GET request using this agent.

pub fn post<T>(&self, uri: T) -> RequestBuilder<WithBody>
where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

Make a POST request using this agent.

pub fn put<T>(&self, uri: T) -> RequestBuilder<WithBody>
where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

Make a PUT request using this agent.

pub fn delete<T>(&self, uri: T) -> RequestBuilder<WithoutBody>
where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

Make a DELETE request using this agent.

pub fn head<T>(&self, uri: T) -> RequestBuilder<WithoutBody>
where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

Make a HEAD request using this agent.

pub fn options<T>(&self, uri: T) -> RequestBuilder<WithoutBody>
where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

Make an OPTIONS request using this agent.

pub fn connect<T>(&self, uri: T) -> RequestBuilder<WithoutBody>
where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

Make a CONNECT request using this agent.

pub fn patch<T>(&self, uri: T) -> RequestBuilder<WithBody>
where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

Make a PATCH request using this agent.

pub fn trace<T>(&self, uri: T) -> RequestBuilder<WithoutBody>
where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

Make a TRACE request using this agent.

Trait Implementations§

§

impl Clone for Agent

§

fn clone(&self) -> Agent

Returns a copy of the value. Read more

1.0.0 · Source§

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

Performs copy-assignment from source. Read more

§

impl Debug for Agent

§

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

Formats the value using the given formatter. Read more

§

impl From<Config> for Agent

§

fn from(value: Config) -> Agent

Converts to this type from the input type.

Auto Trait Implementations§

§

Struct AgentCopy item path

§Example

§About threads and cloning

Implementations§

impl Agent

pub fn new_with_defaults() -> Agent

pub fn new_with_config(config: Config) -> Agent

pub fn config_builder() -> ConfigBuilder<AgentScope>

pub fn with_parts( config: Config, connector: impl Connector, resolver: impl Resolver, ) -> Agent

pub fn run( &self, request: Request<impl AsSendBody>, ) -> Result<Response<Body>, Error> ⓘ

§Example

pub fn config(&self) -> &Config

pub fn configure_request<S>( &self, request: Request<S>, ) -> ConfigBuilder<HttpCrateScope<S>>where S: AsSendBody,

pub fn get<T>(&self, uri: T) -> RequestBuilder<WithoutBody>where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

pub fn post<T>(&self, uri: T) -> RequestBuilder<WithBody>where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

pub fn put<T>(&self, uri: T) -> RequestBuilder<WithBody>where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

pub fn delete<T>(&self, uri: T) -> RequestBuilder<WithoutBody>where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

pub fn head<T>(&self, uri: T) -> RequestBuilder<WithoutBody>where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

pub fn options<T>(&self, uri: T) -> RequestBuilder<WithoutBody>where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

pub fn connect<T>(&self, uri: T) -> RequestBuilder<WithoutBody>where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

pub fn patch<T>(&self, uri: T) -> RequestBuilder<WithBody>where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

pub fn trace<T>(&self, uri: T) -> RequestBuilder<WithoutBody>where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

Trait Implementations§

impl Clone for Agent

fn clone(&self) -> Agent

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

impl Debug for Agent

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

impl From<Config> for Agent

fn from(value: Config) -> Agent

Auto Trait Implementations§

impl Freeze for Agent

impl !RefUnwindSafe for Agent

impl Send for Agent

impl Sync for Agent

impl Unpin for Agent

impl !UnwindSafe for Agent

Blanket Implementations§

impl<T> Any for Twhere T: 'static + ?Sized,

fn type_id(&self) -> TypeId

impl<T> Borrow<T> for Twhere T: ?Sized,

fn borrow(&self) -> &T

impl<T> BorrowMut<T> for Twhere T: ?Sized,

fn borrow_mut(&mut self) -> &mut T

impl<T> ByteSized for T

const BYTE_ALIGN: usize = _

const BYTE_SIZE: usize = _

fn byte_align(&self) -> usize

fn byte_size(&self) -> usize

fn ptr_size_ratio(&self) -> [usize; 2]

impl<T, R> Chain<R> for Twhere T: ?Sized,

fn chain<F>(self, f: F) -> Rwhere F: FnOnce(Self) -> R, Self: Sized,

fn chain_ref<F>(&self, f: F) -> Rwhere F: FnOnce(&Self) -> R,

fn chain_mut<F>(&mut self, f: F) -> Rwhere F: FnOnce(&mut Self) -> R,

impl<T> CloneToUninit for Twhere T: Clone,

unsafe fn clone_to_uninit(&self, dst: *mut u8)

impl<T> ExtAny for Twhere T: Any + ?Sized,

fn type_id() -> TypeId

fn type_of(&self) -> TypeId

fn type_name(&self) -> &'static str ⓘ

fn type_is<T: 'static>(&self) -> bool

fn type_hash(&self) -> u64

fn type_hash_with<H: Hasher>(&self, hasher: H) -> u64

fn as_any_ref(&self) -> &dyn Anywhere Self: Sized,

fn as_any_mut(&mut self) -> &mut dyn Anywhere Self: Sized,

fn as_any_box(self: Box<Self>) -> Box<dyn Any>where Self: Sized,

fn downcast_ref<T: 'static>(&self) -> Option<&T> ⓘ

fn downcast_mut<T: 'static>(&mut self) -> Option<&mut T> ⓘ

impl<T> ExtMem for Twhere T: ?Sized,

const NEEDS_DROP: bool = _

fn mem_align_of<T>() -> usize

fn mem_align_of_val(&self) -> usize

fn mem_size_of<T>() -> usize

fn mem_size_of_val(&self) -> usize

fn mem_copy(&self) -> Selfwhere Self: Copy,

fn mem_needs_drop(&self) -> bool

fn mem_drop(self)where Self: Sized,

fn mem_forget(self)where Self: Sized,

fn mem_replace(&mut self, other: Self) -> Selfwhere Self: Sized,

fn mem_take(&mut self) -> Selfwhere Self: Default,

Struct Agent

pub fn configure_request<S>( &self, request: Request<S>, ) -> ConfigBuilder<HttpCrateScope<S>>
where S: AsSendBody,

pub fn get<T>(&self, uri: T) -> RequestBuilder<WithoutBody>
where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

pub fn post<T>(&self, uri: T) -> RequestBuilder<WithBody>
where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

pub fn put<T>(&self, uri: T) -> RequestBuilder<WithBody>
where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

pub fn delete<T>(&self, uri: T) -> RequestBuilder<WithoutBody>
where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

pub fn head<T>(&self, uri: T) -> RequestBuilder<WithoutBody>
where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

pub fn options<T>(&self, uri: T) -> RequestBuilder<WithoutBody>
where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

pub fn connect<T>(&self, uri: T) -> RequestBuilder<WithoutBody>
where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

pub fn patch<T>(&self, uri: T) -> RequestBuilder<WithBody>
where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

pub fn trace<T>(&self, uri: T) -> RequestBuilder<WithoutBody>
where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

impl<T> Any for T
where T: 'static + ?Sized,

impl<T> Borrow<T> for T
where T: ?Sized,

impl<T> BorrowMut<T> for T
where T: ?Sized,

impl<T, R> Chain<R> for T
where T: ?Sized,

fn chain<F>(self, f: F) -> R
where F: FnOnce(Self) -> R, Self: Sized,

fn chain_ref<F>(&self, f: F) -> R
where F: FnOnce(&Self) -> R,

fn chain_mut<F>(&mut self, f: F) -> R
where F: FnOnce(&mut Self) -> R,

impl<T> CloneToUninit for T
where T: Clone,

impl<T> ExtAny for T
where T: Any + ?Sized,

fn as_any_ref(&self) -> &dyn Any
where Self: Sized,

fn as_any_mut(&mut self) -> &mut dyn Any
where Self: Sized,

fn as_any_box(self: Box<Self>) -> Box<dyn Any>
where Self: Sized,

impl<T> ExtMem for T
where T: ?Sized,

fn mem_copy(&self) -> Self
where Self: Copy,

fn mem_drop(self)
where Self: Sized,

fn mem_forget(self)
where Self: Sized,

fn mem_replace(&mut self, other: Self) -> Self
where Self: Sized,

fn mem_take(&mut self) -> Self
where Self: Default,

fn mem_swap(&mut self, other: &mut Self)
where Self: Sized,

fn mem_as_bytes(&self) -> &[u8] ⓘ
where Self: Sync + Unpin,

fn mem_as_bytes_mut(&mut self) -> &mut [u8] ⓘ
where Self: Sync + Unpin,

fn hook_ref<F>(self, f: F) -> Self
where F: FnOnce(&Self),

fn hook_mut<F>(self, f: F) -> Self
where F: FnOnce(&mut Self),

impl<T, U> Into<U> for T
where U: From<T>,

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

impl<F, T> IntoSample<T> for F
where T: FromSample<F>,

impl<T> ToOwned for T
where T: Clone,

impl<T, U> ToSample<U> for T
where U: FromSample<T>,

impl<T, U> TryFrom<U> for T
where U: Into<T>,

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

impl<S, T> Duplex<S> for T
where T: FromSample<S> + ToSample<S>,

impl<T> Ungil for T
where T: Send,