object_store/client/dns.rs
1// Licensed to the Apache Software Foundation (ASF) under one
2// or more contributor license agreements. See the NOTICE file
3// distributed with this work for additional information
4// regarding copyright ownership. The ASF licenses this file
5// to you under the Apache License, Version 2.0 (the
6// "License"); you may not use this file except in compliance
7// with the License. You may obtain a copy of the License at
8//
9// http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing,
12// software distributed under the License is distributed on an
13// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14// KIND, either express or implied. See the License for the
15// specific language governing permissions and limitations
16// under the License.
17
18//! Customizable DNS resolution for remote object stores
19
20use std::fmt::Debug;
21use std::future::Future;
22use std::net::IpAddr;
23use std::panic::{RefUnwindSafe, UnwindSafe};
24use std::pin::Pin;
25
26/// Error returned by a [`DnsResolver`]
27pub type DnsError = Box<dyn std::error::Error + Send + Sync>;
28
29/// Future returned by [`DnsResolver::resolve`]
30// NOTE: the use cases requiring SocketAddr over IpAddr (i.e., resolver-supplied ports
31// and IPv6 scope IDs) do not apply to object_store, where the port is always
32// determined by the endpoint URL/scheme and endpoints are never link-local.
33pub type DnsFuture = Pin<Box<dyn Future<Output = Result<Vec<IpAddr>, DnsError>> + Send>>;
34
35/// A custom DNS resolver used when establishing connections to remote object stores
36///
37/// This can be used to implement custom resolution logic such as caching,
38/// address shuffling, or split-horizon DNS, independent of the underlying
39/// HTTP transport.
40///
41/// Configure via [`ClientOptions::with_dns_resolver`]. The built-in
42/// reqwest-based transport honors this automatically; custom
43/// [`HttpConnector`] implementations should retrieve it via
44/// [`ClientOptions::dns_resolver`] and apply it themselves.
45///
46/// [`ClientOptions::with_dns_resolver`]: crate::ClientOptions::with_dns_resolver
47/// [`ClientOptions::dns_resolver`]: crate::ClientOptions::dns_resolver
48/// [`HttpConnector`]: crate::client::HttpConnector
49// The `UnwindSafe` bounds preserve the auto traits of `ClientOptions`, which
50// stores an `Arc<dyn DnsResolver>`
51pub trait DnsResolver: Debug + Send + Sync + UnwindSafe + RefUnwindSafe {
52 /// Resolve `host` to one or more IP addresses
53 ///
54 /// The returned addresses are tried in order until a connection succeeds,
55 /// so implementations are responsible for any ordering they require, e.g.
56 /// shuffling or interleaving of address families. The port is determined
57 /// by the transport from the URL, not by the resolver.
58 fn resolve(&self, host: &str) -> DnsFuture;
59}
60
61#[cfg(feature = "reqwest")]
62mod reqwest_impl {
63 use super::{DnsError, DnsFuture, DnsResolver};
64 use rand::prelude::SliceRandom;
65 use std::net::{SocketAddr, ToSocketAddrs};
66 use std::sync::Arc;
67 use tokio::task::JoinSet;
68
69 /// Adapts a [`DnsResolver`] to [`reqwest::dns::Resolve`]
70 ///
71 /// This is deliberately private: it is the only place where [`reqwest`]'s
72 /// resolver API appears, keeping it out of this crate's public interface.
73 pub(crate) struct ReqwestResolver(pub(crate) Arc<dyn DnsResolver>);
74
75 impl reqwest::dns::Resolve for ReqwestResolver {
76 fn resolve(&self, name: reqwest::dns::Name) -> reqwest::dns::Resolving {
77 let resolver = Arc::clone(&self.0);
78 let host = name.as_str().to_string();
79 Box::pin(async move {
80 let ips = resolver.resolve(&host).await?;
81 // Port 0 is a placeholder: reqwest documents that it is replaced
82 // by the port from the URL or the scheme's conventional port
83 let addrs: reqwest::dns::Addrs =
84 Box::new(ips.into_iter().map(|ip| SocketAddr::new(ip, 0)));
85 Ok(addrs)
86 })
87 }
88 }
89
90 /// The built-in shuffling [`DnsResolver`], randomizing the order of the returned
91 /// addresses to spread load across servers, see [`ClientConfigKey::RandomizeAddresses`]
92 ///
93 /// [`ClientConfigKey::RandomizeAddresses`]: crate::ClientConfigKey::RandomizeAddresses
94 #[derive(Debug)]
95 pub(crate) struct ShuffleResolver;
96
97 impl DnsResolver for ShuffleResolver {
98 fn resolve(&self, host: &str) -> DnsFuture {
99 let host = host.to_string();
100 Box::pin(async move {
101 // use `JoinSet` to propagate cancellation to tasks that haven't started running yet.
102 let mut tasks = JoinSet::new();
103 tasks.spawn_blocking(move || {
104 let it = (host.as_str(), 0).to_socket_addrs()?;
105 let mut addrs = it.map(|addr| addr.ip()).collect::<Vec<_>>();
106 addrs.shuffle(&mut rand::rng());
107 Ok(addrs)
108 });
109 tasks
110 .join_next()
111 .await
112 .expect("spawned one task")
113 .map_err(|err| Box::new(err) as DnsError)?
114 })
115 }
116 }
117}
118
119#[cfg(feature = "reqwest")]
120pub(crate) use reqwest_impl::{ReqwestResolver, ShuffleResolver};
121
122#[cfg(all(test, feature = "reqwest"))]
123mod tests {
124 use super::*;
125
126 #[tokio::test]
127 async fn shuffle_resolver_resolves_localhost() {
128 let ips = ShuffleResolver.resolve("localhost").await.unwrap();
129 assert!(!ips.is_empty());
130 assert!(ips.iter().all(|ip| ip.is_loopback()));
131 }
132
133 #[derive(Debug)]
134 struct FailingResolver;
135
136 impl DnsResolver for FailingResolver {
137 fn resolve(&self, _host: &str) -> DnsFuture {
138 Box::pin(async { Err("boom".into()) })
139 }
140 }
141
142 #[tokio::test]
143 async fn adapter_propagates_errors() {
144 use reqwest::dns::Resolve;
145 use std::sync::Arc;
146 let adapter = ReqwestResolver(Arc::new(FailingResolver));
147 let err = match adapter.resolve("localhost".parse().unwrap()).await {
148 Ok(_) => panic!("expected resolution to fail"),
149 Err(e) => e,
150 };
151 assert!(err.to_string().contains("boom"));
152 }
153}