Struct Client 

pub struct Client { /* private fields */ }

Available on crate feature tor only.

A Tor client that exposes capabilities designed for Zcash wallets.

Implementations

impl Client

pub async fn connect_to_lightwalletd( &self, endpoint: Uri, allow_onion_services: bool, ) -> Result<CompactTxStreamerClient<Channel>, Error>

Available on crate feature lightwalletd-tonic-tls-webpki-roots only.

Connects to the lightwalletd server at the given endpoint.

If allow_onion_services is true, the connection will be permitted to reach Tor hidden services (.onion addresses). The caller is responsible for deciding whether onion connections are appropriate for the given endpoint; this crate does not infer that from the endpoint host.

The returned client applies this Client’s Timeouts to every request it makes. Note that the request deadline bounds the wait for a response’s headers, not the duration of the response itself, so long-running streaming methods such as GetBlockRange are not capped by it; a peer that stalls partway through a stream is instead detected by the HTTP/2 keep-alive.

impl Client

pub async fn get_latest_zec_to_usd_rate( &self, rng: &mut impl Rng, exchanges: &Exchanges, ) -> Result<Decimal, Error>

Fetches the latest USD/ZEC exchange rate, derived from the given exchanges.

rng chooses which rate to drop when an odd number of rates is needed.

Returns:

• Ok(rate) if at least one exchange request succeeds.
• Err(_) if none of the exchange queries succeed.

impl Client

pub async fn http_get<T, F: Future<Output = Result<T, Error>>>( &self, url: Uri, request: impl Fn(Builder) -> Builder, parse_response: impl FnOnce(Incoming) -> F, retry_limit: u8, retry_filter: impl Fn(Result<StatusCode, &Error>) -> Option<Retry>, ) -> Result<Response<T>, Error>

Makes an HTTP GET request over Tor.

The request closure can be used to modify or append HTTP request headers. You must not call the following [Builder] methods within it:

• [Builder::method] (this is internally set to GET).
• [Builder::uri] (this is internally set to url).
• [Builder::header] with header name "Host" (this is internally set based on url).

Returns Ok(response) if an HTTP response is received, even if the HTTP status code is not in the 200-299 success range (i.e. HttpError::Unsuccessful is never returned).

There are two arguments for controlling retry behaviour:

• retry_limit is the maximum number of times that a failed request should be retried. You can disable retries by setting this to 0.
• retry_filter can be used to only retry requests that fail in specific ways, and control how the retry is performed. You can disable retries by setting this to |_| None, and you can ensure the same circuit is reused by setting this to |res| res.is_err().then_some(Retry::Same) (e.g. if you require a persistent Tor client identity across queries).

The Timeouts this client was created with are applied to each attempt individually, so the total time this method can take is bounded by retry_limit + 1 times those deadlines. A request that exceeds one of them fails with HttpError::Timeout, which retry_filter sees like any other error.

pub async fn http_post<B, T, F>( &self, url: Uri, request: impl Fn(Builder) -> Builder, body: B, parse_response: impl FnOnce(Incoming) -> F, retry_limit: u8, retry_filter: impl Fn(Result<StatusCode, &Error>) -> Option<Retry>, ) -> Result<Response<T>, Error>

where B: Body + Clone + Send + 'static, B::Data: Send, B::Error: Into<Box<dyn Error + Send + Sync>>, F: Future<Output = Result<T, Error>>,

Makes an HTTP POST request over Tor.

The request closure can be used to modify or append HTTP request headers. You must not call the following [Builder] methods within it:

• [Builder::method] (this is internally set to POST).
• [Builder::uri] (this is internally set to url).
• [Builder::header] with header name "Host" (this is internally set based on url).

Returns Ok(response) if an HTTP response is received, even if the HTTP status code is not in the 200-299 success range (i.e. HttpError::Unsuccessful is never returned).

There are two arguments for controlling retry behaviour:

• retry_limit is the maximum number of times that a failed request should be retried. You can disable retries by setting this to 0.
• retry_filter can be used to only retry requests that fail in specific ways, and control how the retry is performed. You can disable retries by setting this to |_| None, and you can ensure the same circuit is reused by setting this to |res| res.is_err().then_some(Retry::Same) (e.g. if you require a persistent Tor client identity across queries).

The Timeouts this client was created with are applied to each attempt individually, so the total time this method can take is bounded by retry_limit + 1 times those deadlines. A request that exceeds one of them fails with HttpError::Timeout, which retry_filter sees like any other error.

pub async fn http_get_json<T: DeserializeOwned>( &self, url: Uri, request: impl Fn(Builder) -> Builder, retry_limit: u8, retry_filter: impl Fn(Result<StatusCode, &Error>) -> Option<Retry>, ) -> Result<Response<T>, Error>

Makes an HTTP GET request over Tor, parsing the response as JSON.

This is a simple wrapper around Self::http_get. Use that method if you need more control over the response parsing.

The request closure runs first; this method then defaults Accept to application/json only if the closure did not already set it, so a caller can override the default Accept (or add other headers, such as User-Agent) by setting them in the closure. See Self::http_get for the [Builder] methods you must not call within it.

Returns Ok(response) if an HTTP response is received, even if the HTTP status code is not in the 200-299 success range (i.e. HttpError::Unsuccessful is never returned).

There are two arguments for controlling retry behaviour:

• retry_limit is the maximum number of times that a failed request should be retried. You can disable retries by setting this to 0.
• retry_filter can be used to only retry requests that fail in specific ways, and control how the retry is performed. You can disable retries by setting this to |_| None, and you can ensure the same circuit is reused by setting this to |res| res.is_err().then_some(Retry::Same) (e.g. if you require a persistent Tor client identity across queries).

The Timeouts this client was created with are applied to each attempt individually, so the total time this method can take is bounded by retry_limit + 1 times those deadlines. A request that exceeds one of them fails with HttpError::Timeout, which retry_filter sees like any other error.

impl Client

pub async fn create( tor_dir: &Path, with_permissions: impl FnOnce(&mut MistrustBuilder), ) -> Result<Self, Error>

Creates and bootstraps a Tor client with default Timeouts.

The client’s persistent data and cache are both stored in the given directory. Preserving the contents of this directory will speed up subsequent calls to Client::create.

If the with_permissions closure does not make any changes (e.g. is passed as |_| {}), the default from [arti_client] will be used. This default will enable permissions checks unless the ARTI_FS_DISABLE_PERMISSION_CHECKS env variable is set.

Tor requires a process-level rustls [CryptoProvider]. If the application has not installed one, this installs the ring provider as the process default.

Returns an error if tor_dir does not exist, or if bootstrapping fails.

pub async fn create_with_timeouts( tor_dir: &Path, with_permissions: impl FnOnce(&mut MistrustBuilder), timeouts: Timeouts, ) -> Result<Self, Error>

Creates and bootstraps a Tor client that applies the given Timeouts to its network operations.

This is otherwise identical to Client::create; see its documentation for details of the other arguments.

pub fn isolated_client(&self) -> Self

Returns a new isolated tor::Client handle.

The two tor::Clients will share internal state and configuration, but their streams will never share circuits with one another.

Use this method when you want separate parts of your program to each have a tor::Client handle, but where you don’t want their activities to be linkable to one another over the Tor network.

Calling this method is usually preferable to creating a completely separate tor::Client instance, since it can share its internals with the existing tor::Client.

(Connections made with clones of the returned tor::Client may share circuits with each other.)

The returned handle uses the same Timeouts as this one.

pub fn set_dormant(&self, mode: DormantMode)

Changes the client’s current dormant mode, putting background tasks to sleep or waking them up as appropriate.

This can be used to conserve CPU usage if you aren’t planning on using the client for a while, especially on mobile platforms.

See the DormantMode documentation for more details.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.