Expand description
A SIP Rust library implementing RFC 3263, implemented on top of rsip
This library implements all the necessary DNS procedures defined in
RFC3263 that allow a client or a server to
resolve a SIP URI into the (ip, port, transport) tuple. rsip-dns
uses a lazy enumerator
architecture, in a sense of a Stream (but does not implement the Stream trait), which means
any query to the DNS client is performend only when needed.
§Examples
§Create a Context
The first thing you need is to specify a Context which will act as a guide to the Lookup.
The Context, among others, expect anything that implements the DnsClient trait. Refer to
that for more information. rsip-dns
provides a default implementation of that trait
that you can use under the trust-dns
feature flag.
use rsip_dns::*;
use std::net::{IpAddr, Ipv4Addr};
use rsip::{Transport, Port, Host};
let context = Context {
secure: true,
host: Host::from(IpAddr::V4(Ipv4Addr::new(192, 168, 2, 13))),
transport: Some(Transport::Udp),
port: Some(Port::from(5060)),
dns_client: my_dns_client,
supported_transports: Default::default()
};
Here we created a context rather manually, but you can create a context out of a url as well using the Context::initialize_from method:
For example:
use rsip_dns::*;
use rsip::prelude::*;
let uri = rsip::Uri {
scheme: Some(rsip::Scheme::Sip),
host_with_port: ("example.com", 5060).into(),
..Default::default()
};
let context = Context::initialize_from(
uri,
dns_client,
SupportedTransports::any(),
).expect("uri and supported transports don't overlap");
§Lookup
Once you have the Context, then you need to create a Lookup out of it. Basically there is only one (async) method that you are interested to use from Lookup, the resolve_next and this actually comes from ResolvableExt trait.
let mut lookup = Lookup::from(context);
while let target = lookup.resolve_next().await {
match target {
Some(Target {
ip_addr,
port,
transport,
}) => println!("next tuple: ({:?}, {:?}, {:?})", ip_addr, port, transport),
None => break,
}
}
For each iteration, the Lookup makes sure it lazily uses the underlying dns client. For instance, in the case of SRV records, it first resolves the first SRV record for A/AAAA records and then moves to the next. Usually you will find what you want quite fast (in the first 1-2 iterations), but according to RFC3263, if you don’t have port and transport, and NAPTR records are not responding, you might need 10 or even more DNS queries to resolve the peer (ip, port, transport) tuple. Probably the dns client could use some kind of caching, but that’s left up to you, since you need to provide a dns client that implements the DnsClient trait.
§Resolving the next (ip, port, transport) tuple
RFC 3263 explains in detail how the process of figuring out the (ip, port, transport) tuple depending whether a port and/or a transport exists, but basically there are 4 distinct cases:
§1. IP address
In this case an IP address is given, regardless if a port/transport are available.
- if transport is given, then it should be used otherwise the default transport SIP scheme is used (if it’s sip, then TLS, otherwise UDP)
- if port is given, then it should be used, otherwise the default port fot the resolved transport should be used
- use (given ip, given or default port, given or default transport)
§2. Domain with Port
In this case the target is a domain and also a port is given.
- if transport is given as well, then it should be used otherwise the default transport SIP scheme is used (if it’s sip, then TLS, otherwise UDP)
- perform an A or AAAA record lookup for the domain to get the IPs
- for each ip addr found use (resolved ip, given port, given or default transport)
§3. Domain with Transport
- perform a SRV lookup for the supported transport (should take into account sips or sip
scheme here as well)
- for each SRV result, perform an A or AAAA
- for each address record found, use (ip, srv port, given transport)
- for each SRV result, perform an A or AAAA
- if no SRV records are found perform an A or AAAA and to get the ip addrs
- use the default Port for the given transport and try each (ip, default port, given transport)
§4. Domain without Port or Transport
- perform a NAPTR query to get all replacemenets domains
- for each replacement domain, perform a SRV lookup
- filter SRV results based on transports that are supported and then sort based on priority/weight
- for each SRV result, perform an A or AAAA
- for each address record found, use (ip, srv port, srv transport)
- for each replacement domain, perform a SRV lookup
- if no NAPTRs found, build and perform SRV lookup for each transport supported (with & without sips if secure is
supported in context & given transport)
- for each SRV result, perform an A or AAAA
- for each address record found, use (ip, srv port, srv transport)
- for each SRV result, perform an A or AAAA
- if no SRV records are found
- use the default transport depending if it’s SIP or SIPS URI
- use the default Port for the given default transport
- perform an A or AAAA record lookup to get the IPs
- for each ip addr found use (ip, default port, default transport)
§Reusable structure using the ResolvableExt
trait
If you notice on the section above, there are many reusable components. For instance, (2) reuses (1), while (3) reuses (2) (which reuses (1)) and (4) reuses all the previous.
The structure of the code follows this pattern by defining a ResolvableExt
trait,
Resolvable
type and other types that are built on top of Resolvable
or implement
ResolvableExt
trait.
Re-exports§
pub use records::SrvDomain;
pub use resolvables::ResolvableExt;
Modules§
- This module hosts all the DNS types that are used by the Dnsclient.
- This module contains all the resolvable types that are necessary to implement the lazyness async nature of resolving the next (ip, port, transport) tuple of the Lookup.
Structs§
- This is the main context struct that is used by the Lookup to figure out what procedures it should apply. It can manually initialized by populating every field, or by using the Context::initialize_from method which can be handy if you already have the URI of the host.
- Simple struct that allows you to specify whether all
rsip
transports are available or only specific ones. Used here as a type safety to order to avoid edge cases ofOption<Vec<T>>
.. - The (ip, port, transport) tuple resolved that should be used as the next peer target.