detsys_srv/lib.rs
1#![deny(missing_docs)]
2#![warn(rustdoc::broken_intra_doc_links)]
3
4/*!
5Rust client for communicating with services located by DNS SRV records.
6
7# Introduction
8
9SRV Records, as defined in [RFC 2782](https://tools.ietf.org/html/rfc2782),
10are DNS records of the form
11
12`_Service._Proto.Name TTL Class SRV Priority Weight Port Target`
13
14For instance, a DNS server might respond with the following SRV records for
15`_http._tcp.example.com`:
16
17```text
18_http._tcp.example.com. 60 IN SRV 1 100 443 test1.example.com.
19_http._tcp.example.com. 60 IN SRV 2 50 443 test2.example.com.
20_http._tcp.example.com. 60 IN SRV 2 50 443 test3.example.com.
21```
22
23A client wanting to communicate with this example service would first try to
24communicate with `test1.example.com:443` (the record with the lowest
25priority), then with the other two (in a random order, since they are of the
26same priority) should the first be unavailable.
27
28`detsys-srv` handles the lookup and caching of SRV records as well as the ordered
29selection of targets to use for communication with SRV-located services.
30
31[`SrvClient::new`] creates a client (that should be reused to take advantage of
32caching) for communicating with the service located by `_http._tcp.example.com`.
33[`SrvClient::execute`] takes in a future-producing closure (emulating async
34closures, which are currently unstable) and executes the closure on a series of
35targets parsed from the discovered SRV records, stopping and returning the
36first `Ok` or last `Err` it obtains.
37
38# Alternative Resolvers and Target Selection Policies
39
40`detsys-srv` provides multiple resolver backends for SRV lookup and by default uses
41a target selection policy that maintains affinity for the last target it has
42used successfully. Both of these behaviors can be changed by implementing the
43[`SrvResolver`] and [`Policy`] traits, respectively.
44
45
46[`SrvResolver`]: resolver::SrvResolver
47[`Policy`]: policy::Policy
48*/
49
50mod client;
51pub use client::{policy, Error, SrvClient};
52
53mod record;
54pub use record::SrvRecord;
55
56pub mod resolver;