Struct arti_client::TorClient
source · [−]pub struct TorClient<R: Runtime> { /* private fields */ }
Expand description
An active client session on the Tor network.
While it’s running, it will fetch directory information, build circuits, and make connections for you.
Cloning this object makes a new reference to the same underlying
handles: it’s usually better to clone the TorClient
than it is to
create a new one.
Implementations
sourceimpl TorClient<PreferredRuntime>
impl TorClient<PreferredRuntime>
sourcepub async fn create_bootstrapped(config: TorClientConfig) -> Result<Self>
pub async fn create_bootstrapped(config: TorClientConfig) -> Result<Self>
Bootstrap a connection to the Tor network, using the provided config
.
Returns a client once there is enough directory material to connect safely over the Tor network.
Consider using TorClient::builder
for more fine-grained control.
Panics
If Tokio is being used (the default), panics if created outside the context of a currently
running Tokio runtime. See the documentation for PreferredRuntime::current
for
more information.
If using async-std
, either take care to ensure Arti is not compiled with Tokio support,
or manually create an async-std
runtime using tor_rtcompat
and use it with
TorClient::with_runtime
.
sourcepub fn builder() -> TorClientBuilder<PreferredRuntime>
pub fn builder() -> TorClientBuilder<PreferredRuntime>
Return a new builder for creating TorClient objects.
If you want to make a TorClient
synchronously, this is what you want; call
TorClientBuilder::create_unbootstrapped
on the returned builder.
Panics
If Tokio is being used (the default), panics if created outside the context of a currently
running Tokio runtime. See the documentation for tokio::runtime::Handle::current
for
more information.
If using async-std
, either take care to ensure Arti is not compiled with Tokio support,
or manually create an async-std
runtime using tor_rtcompat
and use it with
TorClient::with_runtime
.
sourceimpl<R: Runtime> TorClient<R>
impl<R: Runtime> TorClient<R>
sourcepub fn with_runtime(runtime: R) -> TorClientBuilder<R>
pub fn with_runtime(runtime: R) -> TorClientBuilder<R>
Return a new builder for creating TorClient objects, with a custom provided Runtime
.
See the tor_rtcompat
crate for more information on custom runtimes.
sourcepub async fn bootstrap(&self) -> Result<()>
pub async fn bootstrap(&self) -> Result<()>
Bootstrap a connection to the Tor network, with a client created by create_unbootstrapped
.
Since cloned copies of a TorClient
share internal state, you can bootstrap a client by
cloning it and running this function in a background task (or similar). This function
only needs to be called on one client in order to bootstrap all of its clones.
Returns once there is enough directory material to connect safely over the Tor network. If the client or one of its clones has already been bootstrapped, returns immediately with success. If a bootstrap is in progress, waits for it to finish, then retries it if it failed (returning success if it succeeded).
Bootstrap progress can be tracked by listening to the event receiver returned by
bootstrap_events
.
Failures
If the bootstrapping process fails, returns an error. This function can safely be called again later to attempt to bootstrap another time.
sourcepub fn reconfigure(
&self,
new_config: &TorClientConfig,
how: Reconfigure
) -> Result<()>
pub fn reconfigure(
&self,
new_config: &TorClientConfig,
how: Reconfigure
) -> Result<()>
Change the configuration of this TorClient to new_config
.
The how
describes whether to perform an all-or-nothing
reconfiguration: either all of the configuration changes will be
applied, or none will. If you have disabled all-or-nothing changes, then
only fatal errors will be reported in this function’s return value.
This function applies its changes to all TorClient instances derived
from the same call to TorClient::create_*
: even ones whose circuits
are isolated from this handle.
Limitations
Although most options are reconfigurable, there are some whose values can’t be changed on an a running TorClient. Those options (or their sections) are explicitly documented not to be changeable.
Changing some options do not take effect immediately on all open streams and circuits, but rather affect only future streams and circuits. Those are also explicitly documented.
sourcepub fn isolated_client(&self) -> TorClient<R>
pub fn isolated_client(&self) -> TorClient<R>
Return a new isolated TorClient
handle.
The two TorClient
s will share internal state and configuration, but
their streams will never share circuits with one another.
Use this function when you want separate parts of your program to each have a TorClient handle, but where you don’t want their activities to be linkable to one another over the Tor network.
Calling this function is usually preferable to creating a
completely separate TorClient instance, since it can share its
internals with the existing TorClient
.
(Connections made with clones of the returned TorClient
may
share circuits with each other.)
sourcepub async fn connect<A: IntoTorAddr>(&self, target: A) -> Result<DataStream>
pub async fn connect<A: IntoTorAddr>(&self, target: A) -> Result<DataStream>
Launch an anonymized connection to the provided address and port over the Tor network.
Note that because Tor prefers to do DNS resolution on the remote side of the network, this function takes its address as a string:
// The most usual way to connect is via an address-port tuple.
let socket = tor_client.connect(("www.example.com", 443)).await?;
// You can also specify an address and port as a colon-separated string.
let socket = tor_client.connect("www.example.com:443").await?;
Hostnames are strongly preferred here: if this function allowed the
caller here to provide an IPAddr or IpAddr
or
SocketAddr
address, then
// BAD: We're about to leak our target address to the local resolver!
let address = "www.example.com:443".to_socket_addrs().unwrap().next().unwrap();
// 🤯 Oh no! Now any eavesdropper can tell where we're about to connect! 🤯
// Fortunately, this won't compile, since SocketAddr doesn't implement IntoTorAddr.
// let socket = tor_client.connect(address).await?;
// ^^^^^^^ the trait `IntoTorAddr` is not implemented for `std::net::SocketAddr`
If you really do need to connect to an IP address rather than a hostname, and if you’re sure that the IP address came from a safe location, there are a few ways to do so.
// ⚠️This is risky code!⚠️
// (Make sure your addresses came from somewhere safe...)
// If we have a fixed address, we can just provide it as a string.
let socket = tor_client.connect("192.0.2.22:443").await?;
let socket = tor_client.connect(("192.0.2.22", 443)).await?;
// If we have a SocketAddr or an IpAddr, we can use the
// DangerouslyIntoTorAddr trait.
use arti_client::DangerouslyIntoTorAddr;
let sockaddr = SocketAddr::from(([192, 0, 2, 22], 443));
let ipaddr = IpAddr::from([192, 0, 2, 22]);
let socket = tor_client.connect(sockaddr.into_tor_addr_dangerously().unwrap()).await?;
let socket = tor_client.connect((ipaddr, 443).into_tor_addr_dangerously().unwrap()).await?;
sourcepub async fn connect_with_prefs<A: IntoTorAddr>(
&self,
target: A,
prefs: &StreamPrefs
) -> Result<DataStream>
pub async fn connect_with_prefs<A: IntoTorAddr>(
&self,
target: A,
prefs: &StreamPrefs
) -> Result<DataStream>
Launch an anonymized connection to the provided address and port over the Tor network, with explicit connection preferences.
Note that because Tor prefers to do DNS resolution on the remote
side of the network, this function takes its address as a string.
(See TorClient::connect()
for more information.)
sourcepub fn clone_with_prefs(&self, connect_prefs: StreamPrefs) -> Self
pub fn clone_with_prefs(&self, connect_prefs: StreamPrefs) -> Self
Provides a new handle on this client, but with adjusted default preferences.
Connections made with e.g. connect
on the returned handle will use
connect_prefs
. This is a convenience wrapper for clone
and set_connect_prefs
.
sourcepub async fn resolve(&self, hostname: &str) -> Result<Vec<IpAddr>>
pub async fn resolve(&self, hostname: &str) -> Result<Vec<IpAddr>>
On success, return a list of IP addresses.
sourcepub async fn resolve_with_prefs(
&self,
hostname: &str,
prefs: &StreamPrefs
) -> Result<Vec<IpAddr>>
pub async fn resolve_with_prefs(
&self,
hostname: &str,
prefs: &StreamPrefs
) -> Result<Vec<IpAddr>>
On success, return a list of IP addresses, but use prefs.
sourcepub async fn resolve_ptr(&self, addr: IpAddr) -> Result<Vec<String>>
pub async fn resolve_ptr(&self, addr: IpAddr) -> Result<Vec<String>>
Perform a remote DNS reverse lookup with the provided IP address.
On success, return a list of hostnames.
sourcepub async fn resolve_ptr_with_prefs(
&self,
addr: IpAddr,
prefs: &StreamPrefs
) -> Result<Vec<String>>
pub async fn resolve_ptr_with_prefs(
&self,
addr: IpAddr,
prefs: &StreamPrefs
) -> Result<Vec<String>>
Perform a remote DNS reverse lookup with the provided IP address.
On success, return a list of hostnames.
sourcepub fn bootstrap_status(&self) -> BootstrapStatus
pub fn bootstrap_status(&self) -> BootstrapStatus
Return a current status::BootstrapStatus
describing how close this client
is to being ready for user traffic.
sourcepub fn bootstrap_events(&self) -> BootstrapEvents
pub fn bootstrap_events(&self) -> BootstrapEvents
Return a stream of status::BootstrapStatus
events that will be updated
whenever the client’s status changes.
The receiver might not receive every update sent to this stream, though when it does poll the stream it should get the most recent one.
Trait Implementations
Auto Trait Implementations
impl<R> !RefUnwindSafe for TorClient<R>
impl<R> Send for TorClient<R>
impl<R> Sync for TorClient<R>
impl<R> Unpin for TorClient<R> where
R: Unpin,
impl<R> !UnwindSafe for TorClient<R>
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcepub fn borrow_mut(&mut self) -> &mut T
pub fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> Instrument for T
impl<T> Instrument for T
sourcefn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
sourcefn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
sourceimpl<T> ToOwned for T where
T: Clone,
impl<T> ToOwned for T where
T: Clone,
type Owned = T
type Owned = T
The resulting type after obtaining ownership.
sourcepub fn to_owned(&self) -> T
pub fn to_owned(&self) -> T
Creates owned data from borrowed data, usually by cloning. Read more
sourcepub fn clone_into(&self, target: &mut T)
pub fn clone_into(&self, target: &mut T)
toowned_clone_into
)Uses borrowed data to replace owned data, usually by cloning. Read more
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
pub fn vzip(self) -> V
sourceimpl<T> WithSubscriber for T
impl<T> WithSubscriber for T
sourcefn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
sourcefn with_current_subscriber(self) -> WithDispatch<Self>
fn with_current_subscriber(self) -> WithDispatch<Self>
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more