Trait Connector

pub trait Connector<In = ()>:
    Debug
    + Send
    + Sync
    + 'static
where
    In: Transport,
{
    type Out: Transport;

    // Required method
    fn connect(
        &self,
        details: &ConnectionDetails<'_>,
        chained: Option<In>,
    ) -> Result<Option<Self::Out>, Error> ;

    // Provided method
    fn chain<Next>(self, next: Next) -> ChainedConnector<In, Self, Next>
       where Next: Connector<Self::Out>,
             Self: Sized { ... }
}

Available on crate feature dep_ureq only.

Trait for components providing some aspect of connecting.

A connector instance is reused to produce multiple Transport instances (where Transport instance would typically be a socket connection).

A connector can be part of a chain of connectors. The DefaultConnector provides a chain that first tries to make a concrete socket connection (using TcpConnector) and then pass the resulting Transport to a TLS wrapping connector (see [RustlsConnector]). This makes it possible combine connectors in new ways. A user of ureq could implement bespoke connector (such as SCTP) and still use the RustlsConnector to wrap the underlying transport in TLS.

The built-in DefaultConnector provides SOCKS, TCP sockets and TLS wrapping.

Example

use ureq::{Agent, config::Config};

// These types are not covered by the promises of semver (yet)
use ureq::unversioned::transport::{Connector, TcpConnector, RustlsConnector};
use ureq::unversioned::resolver::DefaultResolver;

// A connector chain that opens a TCP transport, then wraps it in a TLS.
let connector = ()
    .chain(TcpConnector::default())
    .chain(RustlsConnector::default());

let config = Config::default();
let resolver = DefaultResolver::default();

// Creates an agent with a bespoke connector
let agent = Agent::with_parts(config, connector, resolver);

let mut res = agent.get("https://httpbin.org/get").call().unwrap();
let body = res.body_mut().read_to_string().unwrap();

Required Associated Types

type Out: Transport

The type of transport produced by this connector.

Required Methods

fn connect( &self, details: &ConnectionDetails<'_>, chained: Option<In>, ) -> Result<Option<Self::Out>, Error>

Use this connector to make a Transport.

• The ConnectionDetails parameter encapsulates config and the specific details of the connection being made currently (such as the Uri).
• The chained parameter is used for connector chains and contains the Transport instantiated one of the previous connectors in the chain. All Connector instances can decide whether they want to pass this Transport along as is, wrap it in something like TLS or even ignore it to provide some other connection instead.

Returns the Transport as produced by this connector, which could be just the incoming chained argument.

Provided Methods

fn chain<Next>(self, next: Next) -> ChainedConnector<In, Self, Next>

where Next: Connector<Self::Out>, Self: Sized,

Chain this connector to another connector.

This connector will be called first, and the output goes into the next connector.

Implementations on Foreign Types

impl Connector for ()

type Out = ()

fn connect( &self, _: &ConnectionDetails<'_>, _: Option<()>, ) -> Result<Option<<() as Connector>::Out>, Error>

Implementors

impl Connector for DefaultConnector

type Out = Box<dyn Transport>

impl<In> Connector<In> for ConnectProxyConnector

where In: Transport,

type Out = In

impl<In> Connector<In> for TcpConnector

where In: Transport,

type Out = Either<In, TcpTransport>

impl<In, First, Second> Connector<In> for ChainedConnector<In, First, Second>

where In: Transport, First: Connector<In>, Second: Connector<<First as Connector<In>>::Out>,

type Out = <Second as Connector<<First as Connector<In>>::Out>>::Out