Struct srv_rs::SrvClient

pub struct SrvClient<Resolver, Policy: Policy = Affinity> { /* fields omitted */ }

Client for intelligently performing operations on a service located by SRV records.

Usage

After being created by SrvClient::new or SrvClient::new_with_resolver, operations can be performed on the service pointed to by a SrvClient with the execute and execute_stream methods.

DNS Resolvers

The resolver used to lookup SRV records is determined by a client's SrvResolver, and can be set with SrvClient::resolver.

SRV Target Selection Policies

SRV target selection order is determined by a client's Policy, and can be set with SrvClient::policy.

Implementations

impl<Resolver: Default, Policy: Policy + Default> SrvClient<Resolver, Policy>

pub fn new(srv_name: impl ToString) -> Self

Creates a new client for communicating with services located by srv_name.

Examples

use srv_rs::{SrvClient, resolver::libresolv::LibResolv};
let client = SrvClient::<LibResolv>::new("_http._tcp.example.com");

impl<Resolver, Policy: Policy + Default> SrvClient<Resolver, Policy>

pub fn new_with_resolver(srv_name: impl ToString, resolver: Resolver) -> Self

Creates a new client for communicating with services located by srv_name.

impl<Resolver: SrvResolver, Policy: Policy> SrvClient<Resolver, Policy>

pub async fn get_srv_records<'_>(
    &'_ self
) -> Result<(Vec<Resolver::Record>, Instant), Error<Resolver::Error>>

Gets a fresh set of SRV records from a client's DNS resolver, returning them along with the time they're valid until.

pub async fn get_fresh_uri_candidates<'_>(
    &'_ self
) -> Result<(Vec<Uri>, Instant), Error<Resolver::Error>>

Gets a fresh set of SRV records from a client's DNS resolver and parses their target/port pairs into URIs, which are returned along with the time they're valid until--i.e., the time a cache containing these URIs should expire.

pub async fn execute_stream<'a, T, E, Fut>(
    &'a self,
    execution_mode: Execution,
    func: impl FnMut(Uri) -> Fut + 'a
) -> Result<impl Stream<Item = Result<T, E>> + 'a, Error<Resolver::Error>> where
    E: Error,
    Fut: Future<Output = Result<T, E>> + 'a, 

Performs an operation on all of a client's SRV targets, producing a stream of results (one for each target). If the serial execution mode is specified, the operation will be performed on each target in the order determined by the current Policy, and the results will be returned in the same order. If the concurrent execution mode is specified, the operation will be performed on all targets concurrently, and results will be returned in the order they become available.

Examples

use srv_rs::{SrvClient, Error, Execution};
use srv_rs::resolver::libresolv::{LibResolv, LibResolvError};

let results_stream = client.execute_stream(Execution::Serial, |address| async move {
    Ok::<_, std::convert::Infallible>(address.to_string())
})
.await?;
// Do something with the stream, for example collect all results into a `Vec`:
use futures::stream::StreamExt;
let results: Vec<Result<_, _>> = results_stream.collect().await;
for result in results {
    assert!(result.is_ok());
}

pub async fn execute<T, E, Fut, '_>(
    &'_ self,
    execution_mode: Execution,
    func: impl FnMut(Uri) -> Fut
) -> Result<Result<T, E>, Error<Resolver::Error>> where
    E: Error,
    Fut: Future<Output = Result<T, E>>, 

Performs an operation on a client's SRV targets, producing the first successful result or the last error encountered if every execution of the operation was unsuccessful.

Examples

use srv_rs::{SrvClient, Error, Execution};
use srv_rs::resolver::libresolv::{LibResolv, LibResolvError};

let client = SrvClient::<LibResolv>::new(EXAMPLE_SRV);

let res = client.execute(Execution::Serial, |address| async move {
    Ok::<_, std::convert::Infallible>(address.to_string())
})
.await?;
assert!(res.is_ok());

let res = client.execute(Execution::Concurrent, |address| async move {
    address.to_string().parse::<usize>()
})
.await?;
assert!(res.is_err());

impl<Resolver, Policy: Policy> SrvClient<Resolver, Policy>

pub fn srv_name(self, srv_name: impl ToString) -> Self

Sets the SRV name of the client.

pub fn resolver<R>(self, resolver: R) -> SrvClient<R, Policy>

Sets the resolver of the client.

pub fn policy<P: Policy>(self, policy: P) -> SrvClient<Resolver, P>

Sets the policy of the client.

Examples

use srv_rs::{SrvClient, policy::Rfc2782, resolver::libresolv::LibResolv};
let client = SrvClient::<LibResolv>::new(EXAMPLE_SRV).policy(Rfc2782);

pub fn http_scheme(self, http_scheme: Scheme) -> Self

Sets the http scheme of the client.

pub fn path_prefix(self, path_prefix: impl ToString) -> Self

Sets the path prefix of the client.

Trait Implementations

impl<Resolver: Debug, Policy: Debug + Policy> Debug for SrvClient<Resolver, Policy> where
    Policy::CacheItem: Debug, 

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

Formats the value using the given formatter.