From 618db2afaf89e88c3167485711c2f740f586a230 Mon Sep 17 00:00:00 2001 From: nazeh Date: Thu, 7 Nov 2024 12:55:59 +0300 Subject: [PATCH] docs: document using non-zero ports in resolved addresses --- src/async_impl/client.rs | 16 ++++------------ src/blocking/client.rs | 16 ++++------------ src/dns/resolve.rs | 3 +++ 3 files changed, 11 insertions(+), 24 deletions(-) diff --git a/src/async_impl/client.rs b/src/async_impl/client.rs index 1735a1bb1..579050041 100644 --- a/src/async_impl/client.rs +++ b/src/async_impl/client.rs @@ -1858,24 +1858,16 @@ impl ClientBuilder { /// Override DNS resolution for specific domains to a particular IP address. /// - /// Warning - /// - /// Since the DNS protocol has no notion of ports, if you wish to send - /// traffic to a particular port you must include this port in the URL - /// itself, any port in the overridden addr will be ignored and traffic sent - /// to the conventional port for the given scheme (e.g. 80 for http). + /// Set the port to `0` to use the conventional port for the given scheme (e.g. 80 for http). + /// Ports in the URL itself will always be used instead of the port in the overridden addr. pub fn resolve(self, domain: &str, addr: SocketAddr) -> ClientBuilder { self.resolve_to_addrs(domain, &[addr]) } /// Override DNS resolution for specific domains to particular IP addresses. /// - /// Warning - /// - /// Since the DNS protocol has no notion of ports, if you wish to send - /// traffic to a particular port you must include this port in the URL - /// itself, any port in the overridden addresses will be ignored and traffic sent - /// to the conventional port for the given scheme (e.g. 80 for http). + /// Set the port to `0` to use the conventional port for the given scheme (e.g. 80 for http). + /// Ports in the URL itself will always be used instead of the port in the overridden addr. pub fn resolve_to_addrs(mut self, domain: &str, addrs: &[SocketAddr]) -> ClientBuilder { self.config .dns_overrides diff --git a/src/blocking/client.rs b/src/blocking/client.rs index a8c5319b4..73f25208f 100644 --- a/src/blocking/client.rs +++ b/src/blocking/client.rs @@ -945,24 +945,16 @@ impl ClientBuilder { /// Override DNS resolution for specific domains to a particular IP address. /// - /// Warning - /// - /// Since the DNS protocol has no notion of ports, if you wish to send - /// traffic to a particular port you must include this port in the URL - /// itself, any port in the overridden addr will be ignored and traffic sent - /// to the conventional port for the given scheme (e.g. 80 for http). + /// Set the port to `0` to use the conventional port for the given scheme (e.g. 80 for http). + /// Ports in the URL itself will always be used instead of the port in the overridden addr. pub fn resolve(self, domain: &str, addr: SocketAddr) -> ClientBuilder { self.resolve_to_addrs(domain, &[addr]) } /// Override DNS resolution for specific domains to particular IP addresses. /// - /// Warning - /// - /// Since the DNS protocol has no notion of ports, if you wish to send - /// traffic to a particular port you must include this port in the URL - /// itself, any port in the overridden addresses will be ignored and traffic sent - /// to the conventional port for the given scheme (e.g. 80 for http). + /// Set the port to `0` to use the conventional port for the given scheme (e.g. 80 for http). + /// Ports in the URL itself will always be used instead of the port in the overridden addr. pub fn resolve_to_addrs(self, domain: &str, addrs: &[SocketAddr]) -> ClientBuilder { self.with_inner(|inner| inner.resolve_to_addrs(domain, addrs)) } diff --git a/src/dns/resolve.rs b/src/dns/resolve.rs index fe34ecdde..074ede7d2 100644 --- a/src/dns/resolve.rs +++ b/src/dns/resolve.rs @@ -27,6 +27,9 @@ pub trait Resolve: Send + Sync { /// * It does not need a mutable reference to `self`. /// * Since trait objects cannot make use of associated types, it requires /// wrapping the returned `Future` and its contained `Iterator` with `Box`. + /// + /// Explicitly specified port in the URL will override any port in the resolved `SocketAddr`s. + /// Otherwise, port `0` will be replaced by the conventional port for the given scheme (e.g. 80 for http). fn resolve(&self, name: Name) -> Resolving; }