Struct Connector

pub struct Connector<R: Runtime> { /* private fields */ }

Main entrypoint: Object for making HTTP/S requests through Tor.

This type embodies an arti_client::TorClient and implements [ureq::unversioned::transport::Connector], allowing HTTP/HTTPS requests to be made with ureq over Tor.

Also bridges between async I/O (in Arti and Tokio) and sync I/O (in ureq).

A Connector object can be constructed in different ways.

1. Use Connector::new to create a Connector with a default TorClient.

let connector = arti_ureq::Connector::new().expect("Failed to create Connector.");

2. Use Connector::with_tor_client to create a Connector with a specific TorClient.

let tor_client = arti_client::TorClient::with_runtime(
    tor_rtcompat::PreferredRuntime::create().expect("Failed to create runtime.")
)
.create_unbootstrapped()
.expect("Error creating Tor Client.");

let connector = arti_ureq::Connector::with_tor_client(tor_client);

3. Use Connector::builder to create a ConnectorBuilder and configure a Connector with it.

let connector = arti_ureq::Connector::<tor_rtcompat::PreferredRuntime>::builder()
   .expect("Failed to create ConnectorBuilder.")
   .build()
   .expect("Failed to create Connector.");

Usage of Connector.

A Connector can be used to retrieve an [ureq::Agent] with Connector::agent or pass the Connector to [ureq::Agent::with_parts] along with a custom [ureq::config::Config] and a resolver obtained from Connector::resolver to retrieve a more configurable [ureq::Agent].

Retrieve an ureq::Agent.

let connector = arti_ureq::Connector::new().expect("Failed to create Connector.");
let ureq_agent = connector.agent();

Pass as argument to ureq::Agent::with_parts.

We highly advice only using Resolver instead of e.g ureq’s [ureq::unversioned::resolver::DefaultResolver] to avoid DNS leaks.

let connector = arti_ureq::Connector::new().expect("Failed to create Connector.");
let resolver = connector.resolver();

let ureq_agent = ureq::Agent::with_parts(
   ureq::config::Config::default(),
   connector,
   resolver,
);

Implementations

impl<R: Runtime + ToplevelBlockOn> Connector<R>

pub fn with_tor_client(client: TorClient<R>) -> Connector<R>

Creates new instance with the provided arti_client::TorClient.

impl Connector<PreferredRuntime>

pub fn new() -> Result<Self, Error>

Returns new Connector with default values.

To configure a non-default Connector, use ConnectorBuilder.

Warning: This method creates a default arti_client::TorClient. Using multiple concurrent instances of TorClient is not recommended. Most programs should create a single TorClient centrally.

impl<R: Runtime + ToplevelBlockOn> Connector<R>

pub fn resolver(&self) -> Resolver<R>

Returns instance of Resolver implementing trait [ureq::unversioned::resolver::Resolver].

pub fn agent(self) -> Agent

Returns instance of [ureq::Agent].

Equivalent to using [ureq::Agent::with_parts] with the default [ureq::config::Config] and this Connector and the resolver obtained from Connector::resolver().

Example

let ureq_agent = arti_ureq::Connector::new()
    .expect("Failed to create Connector")
    .agent();

// Use the agent to make a request.
ureq_agent
    .get("https://check.torproject.org/api/ip")
    .call()
    .expect("Failed to make request.");

pub fn agent_with_ureq_config(self, config: Config) -> Result<Agent, Error>

Returns instance of [ureq::Agent] using the provided [ureq::config::Config].

Equivalent to Connector::agent but allows the user to provide a custom [ureq::config::Config].

impl<R: Runtime> Connector<R>

Implementation to make ConnectorBuilder accessible from Connector.

Example

let rt = tor_rtcompat::PreferredRuntime::create().expect("Failed to create runtime.");
let tls_provider = arti_ureq::get_default_tls_provider();
    
let client = arti_client::TorClient::with_runtime(rt.clone())
    .create_unbootstrapped()
    .expect("Error creating Tor Client.");

let builder = arti_ureq::ConnectorBuilder::<tor_rtcompat::PreferredRuntime>::new()
    .expect("Failed to create ConnectorBuilder.")
    .tor_client(client)
    .tls_provider(tls_provider);

let arti_connector = builder.build();

pub fn builder() -> Result<ConnectorBuilder<PreferredRuntime>, Error>

Returns new ConnectorBuilder with default values.

Trait Implementations

impl<R: Runtime + ToplevelBlockOn> Connector for Connector<R>

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

Makes a connection using the Tor client.

Returns a HttpTransport which implements trait [ureq::unversioned::transport::Transport].

type Out = Box<dyn Transport>

The type of transport produced by this connector.

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

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

Chain this connector to another connector.

impl<R: Runtime> Debug for Connector<R>

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

Formats the value using the given formatter.