qiniu_http_client/client/resolver/
mod.rs

1mod cache;
2mod chained;
3mod shuffled;
4mod simple;
5mod timeout;
6
7use super::{super::cache::IsCacheValid, ApiResult, RetriedStatsInfo};
8use auto_impl::auto_impl;
9use dyn_clonable::clonable;
10use serde::{Deserialize, Serialize};
11use std::{
12    fmt::Debug,
13    mem::take,
14    net::IpAddr,
15    ops::{Deref, DerefMut},
16};
17
18#[cfg(feature = "async")]
19use futures::future::BoxFuture;
20
21/// 域名解析的接口
22///
23/// 同时提供阻塞接口和异步接口,异步接口则需要启用 `async` 功能
24#[clonable]
25#[auto_impl(&, &mut, Box, Rc, Arc)]
26pub trait Resolver: Clone + Debug + Sync + Send {
27    /// 解析域名
28    ///
29    /// 该方法的异步版本为 [`Self::async_resolve`]。
30    fn resolve(&self, domain: &str, opts: ResolveOptions<'_>) -> ResolveResult;
31
32    /// 异步解析域名
33    #[inline]
34    #[cfg(feature = "async")]
35    #[cfg_attr(feature = "docs", doc(cfg(feature = "async")))]
36    fn async_resolve<'a>(&'a self, domain: &'a str, opts: ResolveOptions<'a>) -> BoxFuture<'a, ResolveResult> {
37        Box::pin(async move { self.resolve(domain, opts) })
38    }
39}
40
41/// 解析域名的选项
42#[derive(Copy, Debug, Clone, Default)]
43pub struct ResolveOptions<'a> {
44    retried: Option<&'a RetriedStatsInfo>,
45}
46
47impl<'a> ResolveOptions<'a> {
48    /// 获取重试统计信息
49    #[inline]
50    pub fn retried(&'a self) -> Option<&'a RetriedStatsInfo> {
51        self.retried
52    }
53
54    /// 创建解析域名的选项构建器
55    #[inline]
56    pub fn builder() -> ResolveOptionsBuilder<'a> {
57        Default::default()
58    }
59}
60
61/// 解析域名的选项构建器
62#[derive(Copy, Debug, Clone, Default)]
63pub struct ResolveOptionsBuilder<'a>(ResolveOptions<'a>);
64
65impl<'a> ResolveOptionsBuilder<'a> {
66    /// 设置重试统计信息
67    #[inline]
68    pub fn retried(&mut self, retried: &'a RetriedStatsInfo) -> &mut Self {
69        self.0.retried = Some(retried);
70        self
71    }
72
73    /// 构建解析域名的选项
74    #[inline]
75    pub fn build(&mut self) -> ResolveOptions<'a> {
76        take(&mut self.0)
77    }
78}
79
80/// 解析结果
81#[derive(Debug, Clone, Serialize, Deserialize)]
82pub struct ResolveAnswers {
83    ip_addrs: Vec<IpAddr>,
84}
85
86impl ResolveAnswers {
87    /// 获取 IP 地址列表
88    #[inline]
89    pub fn ip_addrs(&self) -> &[IpAddr] {
90        &self.ip_addrs
91    }
92
93    /// 获取 IP 地址列表的可变引用
94    #[inline]
95    pub fn ip_addrs_mut(&mut self) -> &mut Vec<IpAddr> {
96        &mut self.ip_addrs
97    }
98
99    /// 转换为 IP 地址列表
100    #[inline]
101    pub fn into_ip_addrs(self) -> Vec<IpAddr> {
102        self.ip_addrs
103    }
104}
105
106impl IsCacheValid for ResolveAnswers {}
107
108impl From<Box<[IpAddr]>> for ResolveAnswers {
109    #[inline]
110    fn from(ip_addrs: Box<[IpAddr]>) -> Self {
111        Self {
112            ip_addrs: ip_addrs.into(),
113        }
114    }
115}
116
117impl From<Vec<IpAddr>> for ResolveAnswers {
118    #[inline]
119    fn from(ip_addrs: Vec<IpAddr>) -> Self {
120        Self { ip_addrs }
121    }
122}
123
124impl FromIterator<IpAddr> for ResolveAnswers {
125    #[inline]
126    fn from_iter<T: IntoIterator<Item = IpAddr>>(iter: T) -> Self {
127        Self {
128            ip_addrs: Vec::from_iter(iter),
129        }
130    }
131}
132
133impl<'a> IntoIterator for &'a ResolveAnswers {
134    type Item = &'a IpAddr;
135    type IntoIter = std::slice::Iter<'a, IpAddr>;
136
137    #[inline]
138    fn into_iter(self) -> Self::IntoIter {
139        self.ip_addrs.iter()
140    }
141}
142
143impl Extend<IpAddr> for ResolveAnswers {
144    fn extend<T: IntoIterator<Item = IpAddr>>(&mut self, iter: T) {
145        self.ip_addrs.extend(iter);
146    }
147}
148
149impl From<ResolveAnswers> for Box<[IpAddr]> {
150    #[inline]
151    fn from(answers: ResolveAnswers) -> Self {
152        answers.ip_addrs.into()
153    }
154}
155
156impl From<ResolveAnswers> for Vec<IpAddr> {
157    #[inline]
158    fn from(answers: ResolveAnswers) -> Self {
159        answers.ip_addrs
160    }
161}
162
163impl AsRef<[IpAddr]> for ResolveAnswers {
164    #[inline]
165    fn as_ref(&self) -> &[IpAddr] {
166        &self.ip_addrs
167    }
168}
169
170impl AsMut<[IpAddr]> for ResolveAnswers {
171    #[inline]
172    fn as_mut(&mut self) -> &mut [IpAddr] {
173        &mut self.ip_addrs
174    }
175}
176
177impl Deref for ResolveAnswers {
178    type Target = [IpAddr];
179
180    #[inline]
181    fn deref(&self) -> &Self::Target {
182        &self.ip_addrs
183    }
184}
185
186impl DerefMut for ResolveAnswers {
187    #[inline]
188    fn deref_mut(&mut self) -> &mut Self::Target {
189        &mut self.ip_addrs
190    }
191}
192
193/// 域名解析结果
194pub type ResolveResult = ApiResult<ResolveAnswers>;
195
196pub use cache::{CachedResolver, CachedResolverBuilder};
197pub use chained::{ChainedResolver, ChainedResolverBuilder};
198pub use shuffled::ShuffledResolver;
199pub use simple::SimpleResolver;
200pub use timeout::TimeoutResolver;
201
202mod owned_resolver_options;
203
204#[cfg(feature = "c_ares")]
205mod c_ares_impl;
206
207#[cfg(feature = "c_ares")]
208pub use c_ares_impl::{c_ares, c_ares_resolver, CAresResolver};
209
210#[cfg(all(feature = "trust_dns", feature = "async"))]
211mod trust_dns;
212
213#[cfg(all(feature = "trust_dns", feature = "async"))]
214pub use trust_dns::{trust_dns_resolver, TrustDnsResolver};