pub struct StreamPrefs {
    ip_ver_pref: IpVersionPreference,
    isolation: StreamIsolationPreference,
    optimistic_stream: bool,
    country_code: Option<CountryCode>,
    pub(crate) connect_to_onion_services: BoolOrAuto,
}
Expand description

Preferences for how to route a stream over the Tor network.

Fields§

§ip_ver_pref: IpVersionPreference

What kind of IPv6/IPv4 we’d prefer, and how strongly.

§isolation: StreamIsolationPreference

How should we isolate connection(s)?

§optimistic_stream: bool

Whether to return the stream optimistically.

§country_code: Option<CountryCode>
Available on crate feature geoip only.

A country to restrict the exit relay’s location to.

§connect_to_onion_services: BoolOrAuto
Available on crate feature onion-service-client only.

Whether to try to make connections to onion services.

Auto means to use the client configuration.

Implementations§

source§

impl StreamPrefs

source

pub fn new() -> Self

Construct a new StreamPrefs.

source

pub fn ipv6_preferred(&mut self) -> &mut Self

Indicate that a stream may be made over IPv4 or IPv6, but that we’d prefer IPv6.

source

pub fn ipv6_only(&mut self) -> &mut Self

Indicate that a stream may only be made over IPv6.

When this option is set, we will only pick exit relays that support IPv6, and we will tell them to only give us IPv6 connections.

source

pub fn ipv4_preferred(&mut self) -> &mut Self

Indicate that a stream may be made over IPv4 or IPv6, but that we’d prefer IPv4.

This is the default.

source

pub fn ipv4_only(&mut self) -> &mut Self

Indicate that a stream may only be made over IPv4.

When this option is set, we will only pick exit relays that support IPv4, and we will tell them to only give us IPv4 connections.

source

pub fn exit_country(&mut self, country_code: CountryCode) -> &mut Self

Available on crate feature geoip only.

Indicate that a stream should appear to come from the given country.

When this option is set, we will only pick exit relays that have an IP address that matches the country in our GeoIP database.

source

pub fn any_exit_country(&mut self) -> &mut Self

Indicate that we don’t care which country a stream appears to come from.

This is available even in the case where GeoIP support is compiled out, to make things easier.

source

pub fn optimistic(&mut self) -> &mut Self

Indicate that the stream should be opened “optimistically”.

By default, streams are not “optimistic”. When you call TorClient::connect(), it won’t give you a stream until the exit node has confirmed that it has successfully opened a connection to your target address. It’s safer to wait in this way, but it is slower: it takes an entire round trip to get your confirmation.

If a stream is configured to be “optimistic”, on the other hand, then TorClient::connect() will return the stream immediately, without waiting for an answer from the exit. You can start sending data on the stream right away, though of course this data will be lost if the connection is not actually successful.

source

pub fn connect_to_onion_services( &mut self, connect_to_onion_services: BoolOrAuto ) -> &mut Self

Available on crate feature onion-service-client only.

Indicate whether connection to a hidden service (.onion service) should be allowed

If Explicit(false), attempts to connect to Onion Services will be forced to fail with an error of kind InvalidStreamTarget.

If Explicit(true), Onion Service connections are enabled.

If Auto, the behaviour depends on the address_filter.allow_onion_addrs configuration option, which is in turn disabled by default.

Note: Arti currently lacks the “vanguards” feature that Tor uses to prevent guard discovery attacks over time. As such, you should probably stick with C Tor if you need to make a large number of onion service connections, or if you are using the Tor protocol in a way that lets an attacker control how many onion services connections that you make - for example, when using Arti’s SOCKS support from a web browser such as Tor Browser.

source

fn wrap_target_port(&self, port: u16) -> TargetPort

Return a TargetPort to describe what kind of exit policy our target circuit needs to support.

source

fn stream_parameters(&self) -> StreamParameters

Return a new StreamParameters based on this configuration.

source

pub fn new_isolation_group(&mut self) -> &mut Self

Indicate that connections with these preferences should have their own isolation group

This is a convenience method which creates a fresh IsolationToken and sets it for these preferences.

This connection preference is orthogonal to isolation established by TorClient::isolated_client. Connections made with an isolated_client (and its clones) will not share circuits with the original client, even if the same isolation is specified via the ConnectionPrefs in force.

source

pub fn set_isolation<T>(&mut self, isolation: T) -> &mut Self
where T: Into<Box<dyn Isolation>>,

Indicate which other connections might use the same circuit as this one.

By default all connections made on all clones of a TorClient may share connections. Connections made with a particular isolation may share circuits with each other.

This connection preference is orthogonal to isolation established by TorClient::isolated_client. Connections made with an isolated_client (and its clones) will not share circuits with the original client, even if the same isolation is specified via the ConnectionPrefs in force.

source

pub fn isolate_every_stream(&mut self) -> &mut Self

Indicate that no connection should share a circuit with any other.

Use with care: This is likely to have poor performance, and imposes a much greater load on the Tor network. Use this option only to make small numbers of connections each of which needs to be isolated from all other connections.

(Don’t just use this as a “get more privacy!!” method: the circuits that it put connections on will have no more privacy than any other circuits. The only benefit is that these circuits will not be shared by multiple streams.)

This can be undone by calling set_isolation or new_isolation_group on these preferences.

source

fn prefs_isolation(&self) -> Option<Box<dyn Isolation>>

Return an Isolation which separates according to these StreamPrefs (only)

This describes which connections or operations might use the same circuit(s) as this one.

Since this doesn’t have access to the TorClient, it doesn’t separate streams which ought to be separated because of the way their TorClients are isolated. For that, use TorClient::isolation.

Trait Implementations§

source§

impl Clone for StreamPrefs

source§

fn clone(&self) -> StreamPrefs

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
source§

impl Debug for StreamPrefs

source§

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

Formats the value using the given formatter. Read more
source§

impl Default for StreamPrefs

source§

fn default() -> StreamPrefs

Returns the “default value” for a type. Read more

Auto Trait Implementations§

Blanket Implementations§

source§

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

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

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

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

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

source§

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

Mutably borrows from an owned value. Read more
§

impl<T> Conv for T

§

fn conv<T>(self) -> T
where Self: Into<T>,

Converts self into T using Into<T>. Read more
§

impl<T> Downcast for T
where T: Any,

§

fn into_any(self: Box<T>) -> Box<dyn Any>

Convert Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can then be further downcast into Box<ConcreteType> where ConcreteType implements Trait.
§

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

Convert Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be further downcast into Rc<ConcreteType> where ConcreteType implements Trait.
§

fn as_any(&self) -> &(dyn Any + 'static)

Convert &Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &Any’s vtable from &Trait’s.
§

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s.
§

impl<T> DowncastSync for T
where T: Any + Send + Sync,

§

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

Convert Arc<Trait> (where Trait: Downcast) to Arc<Any>. Arc<Any> can then be further downcast into Arc<ConcreteType> where ConcreteType implements Trait.
source§

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

§

impl<T> FmtForward for T

§

fn fmt_binary(self) -> FmtBinary<Self>
where Self: Binary,

Causes self to use its Binary implementation when Debug-formatted.
§

fn fmt_display(self) -> FmtDisplay<Self>
where Self: Display,

Causes self to use its Display implementation when Debug-formatted.
§

fn fmt_lower_exp(self) -> FmtLowerExp<Self>
where Self: LowerExp,

Causes self to use its LowerExp implementation when Debug-formatted.
§

fn fmt_lower_hex(self) -> FmtLowerHex<Self>
where Self: LowerHex,

Causes self to use its LowerHex implementation when Debug-formatted.
§

fn fmt_octal(self) -> FmtOctal<Self>
where Self: Octal,

Causes self to use its Octal implementation when Debug-formatted.
§

fn fmt_pointer(self) -> FmtPointer<Self>
where Self: Pointer,

Causes self to use its Pointer implementation when Debug-formatted.
§

fn fmt_upper_exp(self) -> FmtUpperExp<Self>
where Self: UpperExp,

Causes self to use its UpperExp implementation when Debug-formatted.
§

fn fmt_upper_hex(self) -> FmtUpperHex<Self>
where Self: UpperHex,

Causes self to use its UpperHex implementation when Debug-formatted.
§

fn fmt_list(self) -> FmtList<Self>
where &'a Self: for<'a> IntoIterator,

Formats each item in a sequence. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

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

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

§

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

§

fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> R
where Self: Sized,

Pipes by value. This is generally the method you want to use. Read more
§

fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> R
where R: 'a,

Borrows self and passes that borrow into the pipe function. Read more
§

fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> R
where R: 'a,

Mutably borrows self and passes that borrow into the pipe function. Read more
§

fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> R
where Self: Borrow<B>, B: 'a + ?Sized, R: 'a,

Borrows self, then passes self.borrow() into the pipe function. Read more
§

fn pipe_borrow_mut<'a, B, R>( &'a mut self, func: impl FnOnce(&'a mut B) -> R ) -> R
where Self: BorrowMut<B>, B: 'a + ?Sized, R: 'a,

Mutably borrows self, then passes self.borrow_mut() into the pipe function. Read more
§

fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R
where Self: AsRef<U>, U: 'a + ?Sized, R: 'a,

Borrows self, then passes self.as_ref() into the pipe function.
§

fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> R
where Self: AsMut<U>, U: 'a + ?Sized, R: 'a,

Mutably borrows self, then passes self.as_mut() into the pipe function.
§

fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R
where Self: Deref<Target = T>, T: 'a + ?Sized, R: 'a,

Borrows self, then passes self.deref() into the pipe function.
§

fn pipe_deref_mut<'a, T, R>( &'a mut self, func: impl FnOnce(&'a mut T) -> R ) -> R
where Self: DerefMut<Target = T> + Deref, T: 'a + ?Sized, R: 'a,

Mutably borrows self, then passes self.deref_mut() into the pipe function.
source§

impl<T> Same for T

§

type Output = T

Should always be Self
§

impl<T> Tap for T

§

fn tap(self, func: impl FnOnce(&Self)) -> Self

Immutable access to a value. Read more
§

fn tap_mut(self, func: impl FnOnce(&mut Self)) -> Self

Mutable access to a value. Read more
§

fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self
where Self: Borrow<B>, B: ?Sized,

Immutable access to the Borrow<B> of a value. Read more
§

fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self
where Self: BorrowMut<B>, B: ?Sized,

Mutable access to the BorrowMut<B> of a value. Read more
§

fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self
where Self: AsRef<R>, R: ?Sized,

Immutable access to the AsRef<R> view of a value. Read more
§

fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self
where Self: AsMut<R>, R: ?Sized,

Mutable access to the AsMut<R> view of a value. Read more
§

fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self
where Self: Deref<Target = T>, T: ?Sized,

Immutable access to the Deref::Target of a value. Read more
§

fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self
where Self: DerefMut<Target = T> + Deref, T: ?Sized,

Mutable access to the Deref::Target of a value. Read more
§

fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self

Calls .tap() only in debug builds, and is erased in release builds.
§

fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self

Calls .tap_mut() only in debug builds, and is erased in release builds.
§

fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self
where Self: Borrow<B>, B: ?Sized,

Calls .tap_borrow() only in debug builds, and is erased in release builds.
§

fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self
where Self: BorrowMut<B>, B: ?Sized,

Calls .tap_borrow_mut() only in debug builds, and is erased in release builds.
§

fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self
where Self: AsRef<R>, R: ?Sized,

Calls .tap_ref() only in debug builds, and is erased in release builds.
§

fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self
where Self: AsMut<R>, R: ?Sized,

Calls .tap_ref_mut() only in debug builds, and is erased in release builds.
§

fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self
where Self: Deref<Target = T>, T: ?Sized,

Calls .tap_deref() only in debug builds, and is erased in release builds.
§

fn tap_deref_mut_dbg<T>(self, func: impl FnOnce(&mut T)) -> Self
where Self: DerefMut<Target = T> + Deref, T: ?Sized,

Calls .tap_deref_mut() only in debug builds, and is erased in release builds.
source§

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

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
§

impl<T> TryConv for T

§

fn try_conv<T>(self) -> Result<T, Self::Error>
where Self: TryInto<T>,

Attempts to convert self into T using TryInto<T>. Read more
source§

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

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

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

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

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
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more