Struct arti_client::client::StreamPrefs

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

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

impl StreamPrefs

pub fn new() -> Self

Construct a new StreamPrefs.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

fn stream_parameters(&self) -> StreamParameters

Return a new StreamParameters based on this configuration.

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.

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.

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.

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

impl Clone for StreamPrefs

fn clone(&self) -> StreamPrefs

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for StreamPrefs

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

Formats the value using the given formatter.

impl Default for StreamPrefs

fn default() -> StreamPrefs

Returns the “default value” for a type.