1 | // Tests for this module |
2 | #[cfg (all(test, not(any(target_os = "emscripten" , all(target_os = "wasi" , target_env = "p1" )))))] |
3 | mod tests; |
4 | |
5 | #[stable (feature = "rust1" , since = "1.0.0" )] |
6 | pub use core::net::{SocketAddr, SocketAddrV4, SocketAddrV6}; |
7 | |
8 | use crate::net::{IpAddr, Ipv4Addr, Ipv6Addr}; |
9 | use crate::sys::net::LookupHost; |
10 | use crate::{io, iter, option, slice, vec}; |
11 | |
12 | /// A trait for objects which can be converted or resolved to one or more |
13 | /// [`SocketAddr`] values. |
14 | /// |
15 | /// This trait is used for generic address resolution when constructing network |
16 | /// objects. By default it is implemented for the following types: |
17 | /// |
18 | /// * [`SocketAddr`]: [`to_socket_addrs`] is the identity function. |
19 | /// |
20 | /// * [`SocketAddrV4`], [`SocketAddrV6`], <code>([IpAddr], [u16])</code>, |
21 | /// <code>([Ipv4Addr], [u16])</code>, <code>([Ipv6Addr], [u16])</code>: |
22 | /// [`to_socket_addrs`] constructs a [`SocketAddr`] trivially. |
23 | /// |
24 | /// * <code>(&[str], [u16])</code>: <code>&[str]</code> should be either a string representation |
25 | /// of an [`IpAddr`] address as expected by [`FromStr`] implementation or a host |
26 | /// name. [`u16`] is the port number. |
27 | /// |
28 | /// * <code>&[str]</code>: the string should be either a string representation of a |
29 | /// [`SocketAddr`] as expected by its [`FromStr`] implementation or a string like |
30 | /// `<host_name>:<port>` pair where `<port>` is a [`u16`] value. |
31 | /// |
32 | /// This trait allows constructing network objects like [`TcpStream`] or |
33 | /// [`UdpSocket`] easily with values of various types for the bind/connection |
34 | /// address. It is needed because sometimes one type is more appropriate than |
35 | /// the other: for simple uses a string like `"localhost:12345"` is much nicer |
36 | /// than manual construction of the corresponding [`SocketAddr`], but sometimes |
37 | /// [`SocketAddr`] value is *the* main source of the address, and converting it to |
38 | /// some other type (e.g., a string) just for it to be converted back to |
39 | /// [`SocketAddr`] in constructor methods is pointless. |
40 | /// |
41 | /// Addresses returned by the operating system that are not IP addresses are |
42 | /// silently ignored. |
43 | /// |
44 | /// [`FromStr`]: crate::str::FromStr "std::str::FromStr" |
45 | /// [`TcpStream`]: crate::net::TcpStream "net::TcpStream" |
46 | /// [`to_socket_addrs`]: ToSocketAddrs::to_socket_addrs |
47 | /// [`UdpSocket`]: crate::net::UdpSocket "net::UdpSocket" |
48 | /// |
49 | /// # Examples |
50 | /// |
51 | /// Creating a [`SocketAddr`] iterator that yields one item: |
52 | /// |
53 | /// ``` |
54 | /// use std::net::{ToSocketAddrs, SocketAddr}; |
55 | /// |
56 | /// let addr = SocketAddr::from(([127, 0, 0, 1], 443)); |
57 | /// let mut addrs_iter = addr.to_socket_addrs().unwrap(); |
58 | /// |
59 | /// assert_eq!(Some(addr), addrs_iter.next()); |
60 | /// assert!(addrs_iter.next().is_none()); |
61 | /// ``` |
62 | /// |
63 | /// Creating a [`SocketAddr`] iterator from a hostname: |
64 | /// |
65 | /// ```no_run |
66 | /// use std::net::{SocketAddr, ToSocketAddrs}; |
67 | /// |
68 | /// // assuming 'localhost' resolves to 127.0.0.1 |
69 | /// let mut addrs_iter = "localhost:443" .to_socket_addrs().unwrap(); |
70 | /// assert_eq!(addrs_iter.next(), Some(SocketAddr::from(([127, 0, 0, 1], 443)))); |
71 | /// assert!(addrs_iter.next().is_none()); |
72 | /// |
73 | /// // assuming 'foo' does not resolve |
74 | /// assert!("foo:443" .to_socket_addrs().is_err()); |
75 | /// ``` |
76 | /// |
77 | /// Creating a [`SocketAddr`] iterator that yields multiple items: |
78 | /// |
79 | /// ``` |
80 | /// use std::net::{SocketAddr, ToSocketAddrs}; |
81 | /// |
82 | /// let addr1 = SocketAddr::from(([0, 0, 0, 0], 80)); |
83 | /// let addr2 = SocketAddr::from(([127, 0, 0, 1], 443)); |
84 | /// let addrs = vec![addr1, addr2]; |
85 | /// |
86 | /// let mut addrs_iter = (&addrs[..]).to_socket_addrs().unwrap(); |
87 | /// |
88 | /// assert_eq!(Some(addr1), addrs_iter.next()); |
89 | /// assert_eq!(Some(addr2), addrs_iter.next()); |
90 | /// assert!(addrs_iter.next().is_none()); |
91 | /// ``` |
92 | /// |
93 | /// Attempting to create a [`SocketAddr`] iterator from an improperly formatted |
94 | /// socket address `&str` (missing the port): |
95 | /// |
96 | /// ``` |
97 | /// use std::io; |
98 | /// use std::net::ToSocketAddrs; |
99 | /// |
100 | /// let err = "127.0.0.1" .to_socket_addrs().unwrap_err(); |
101 | /// assert_eq!(err.kind(), io::ErrorKind::InvalidInput); |
102 | /// ``` |
103 | /// |
104 | /// [`TcpStream::connect`] is an example of an function that utilizes |
105 | /// `ToSocketAddrs` as a trait bound on its parameter in order to accept |
106 | /// different types: |
107 | /// |
108 | /// ```no_run |
109 | /// use std::net::{TcpStream, Ipv4Addr}; |
110 | /// |
111 | /// let stream = TcpStream::connect(("127.0.0.1" , 443)); |
112 | /// // or |
113 | /// let stream = TcpStream::connect("127.0.0.1:443" ); |
114 | /// // or |
115 | /// let stream = TcpStream::connect((Ipv4Addr::new(127, 0, 0, 1), 443)); |
116 | /// ``` |
117 | /// |
118 | /// [`TcpStream::connect`]: crate::net::TcpStream::connect |
119 | #[stable (feature = "rust1" , since = "1.0.0" )] |
120 | pub trait ToSocketAddrs { |
121 | /// Returned iterator over socket addresses which this type may correspond |
122 | /// to. |
123 | #[stable (feature = "rust1" , since = "1.0.0" )] |
124 | type Iter: Iterator<Item = SocketAddr>; |
125 | |
126 | /// Converts this object to an iterator of resolved [`SocketAddr`]s. |
127 | /// |
128 | /// The returned iterator might not actually yield any values depending on the |
129 | /// outcome of any resolution performed. |
130 | /// |
131 | /// Note that this function may block the current thread while resolution is |
132 | /// performed. |
133 | #[stable (feature = "rust1" , since = "1.0.0" )] |
134 | fn to_socket_addrs(&self) -> io::Result<Self::Iter>; |
135 | } |
136 | |
137 | #[stable (feature = "rust1" , since = "1.0.0" )] |
138 | impl ToSocketAddrs for SocketAddr { |
139 | type Iter = option::IntoIter<SocketAddr>; |
140 | fn to_socket_addrs(&self) -> io::Result<option::IntoIter<SocketAddr>> { |
141 | Ok(Some(*self).into_iter()) |
142 | } |
143 | } |
144 | |
145 | #[stable (feature = "rust1" , since = "1.0.0" )] |
146 | impl ToSocketAddrs for SocketAddrV4 { |
147 | type Iter = option::IntoIter<SocketAddr>; |
148 | fn to_socket_addrs(&self) -> io::Result<option::IntoIter<SocketAddr>> { |
149 | SocketAddr::V4(*self).to_socket_addrs() |
150 | } |
151 | } |
152 | |
153 | #[stable (feature = "rust1" , since = "1.0.0" )] |
154 | impl ToSocketAddrs for SocketAddrV6 { |
155 | type Iter = option::IntoIter<SocketAddr>; |
156 | fn to_socket_addrs(&self) -> io::Result<option::IntoIter<SocketAddr>> { |
157 | SocketAddr::V6(*self).to_socket_addrs() |
158 | } |
159 | } |
160 | |
161 | #[stable (feature = "rust1" , since = "1.0.0" )] |
162 | impl ToSocketAddrs for (IpAddr, u16) { |
163 | type Iter = option::IntoIter<SocketAddr>; |
164 | fn to_socket_addrs(&self) -> io::Result<option::IntoIter<SocketAddr>> { |
165 | let (ip: IpAddr, port: u16) = *self; |
166 | match ip { |
167 | IpAddr::V4(ref a: &Ipv4Addr) => (*a, port).to_socket_addrs(), |
168 | IpAddr::V6(ref a: &Ipv6Addr) => (*a, port).to_socket_addrs(), |
169 | } |
170 | } |
171 | } |
172 | |
173 | #[stable (feature = "rust1" , since = "1.0.0" )] |
174 | impl ToSocketAddrs for (Ipv4Addr, u16) { |
175 | type Iter = option::IntoIter<SocketAddr>; |
176 | fn to_socket_addrs(&self) -> io::Result<option::IntoIter<SocketAddr>> { |
177 | let (ip: Ipv4Addr, port: u16) = *self; |
178 | SocketAddrV4::new(ip, port).to_socket_addrs() |
179 | } |
180 | } |
181 | |
182 | #[stable (feature = "rust1" , since = "1.0.0" )] |
183 | impl ToSocketAddrs for (Ipv6Addr, u16) { |
184 | type Iter = option::IntoIter<SocketAddr>; |
185 | fn to_socket_addrs(&self) -> io::Result<option::IntoIter<SocketAddr>> { |
186 | let (ip: Ipv6Addr, port: u16) = *self; |
187 | SocketAddrV6::new(ip, port, flowinfo:0, scope_id:0).to_socket_addrs() |
188 | } |
189 | } |
190 | |
191 | fn resolve_socket_addr(lh: LookupHost) -> io::Result<vec::IntoIter<SocketAddr>> { |
192 | let p: u16 = lh.port(); |
193 | let v: Vec<_> = lhimpl Iterator |
194 | .map(|mut a: SocketAddr| { |
195 | a.set_port(new_port:p); |
196 | a |
197 | }) |
198 | .collect(); |
199 | Ok(v.into_iter()) |
200 | } |
201 | |
202 | #[stable (feature = "rust1" , since = "1.0.0" )] |
203 | impl ToSocketAddrs for (&str, u16) { |
204 | type Iter = vec::IntoIter<SocketAddr>; |
205 | fn to_socket_addrs(&self) -> io::Result<vec::IntoIter<SocketAddr>> { |
206 | let (host: &str, port: u16) = *self; |
207 | |
208 | // try to parse the host as a regular IP address first |
209 | if let Ok(addr: Ipv4Addr) = host.parse::<Ipv4Addr>() { |
210 | let addr: SocketAddrV4 = SocketAddrV4::new(ip:addr, port); |
211 | return Ok(vec![SocketAddr::V4(addr)].into_iter()); |
212 | } |
213 | if let Ok(addr: Ipv6Addr) = host.parse::<Ipv6Addr>() { |
214 | let addr: SocketAddrV6 = SocketAddrV6::new(ip:addr, port, flowinfo:0, scope_id:0); |
215 | return Ok(vec![SocketAddr::V6(addr)].into_iter()); |
216 | } |
217 | |
218 | resolve_socket_addr((host, port).try_into()?) |
219 | } |
220 | } |
221 | |
222 | #[stable (feature = "string_u16_to_socket_addrs" , since = "1.46.0" )] |
223 | impl ToSocketAddrs for (String, u16) { |
224 | type Iter = vec::IntoIter<SocketAddr>; |
225 | fn to_socket_addrs(&self) -> io::Result<vec::IntoIter<SocketAddr>> { |
226 | (&*self.0, self.1).to_socket_addrs() |
227 | } |
228 | } |
229 | |
230 | // accepts strings like 'localhost:12345' |
231 | #[stable (feature = "rust1" , since = "1.0.0" )] |
232 | impl ToSocketAddrs for str { |
233 | type Iter = vec::IntoIter<SocketAddr>; |
234 | fn to_socket_addrs(&self) -> io::Result<vec::IntoIter<SocketAddr>> { |
235 | // try to parse as a regular SocketAddr first |
236 | if let Ok(addr: SocketAddr) = self.parse() { |
237 | return Ok(vec![addr].into_iter()); |
238 | } |
239 | |
240 | resolve_socket_addr(self.try_into()?) |
241 | } |
242 | } |
243 | |
244 | #[stable (feature = "slice_to_socket_addrs" , since = "1.8.0" )] |
245 | impl<'a> ToSocketAddrs for &'a [SocketAddr] { |
246 | type Iter = iter::Cloned<slice::Iter<'a, SocketAddr>>; |
247 | |
248 | fn to_socket_addrs(&self) -> io::Result<Self::Iter> { |
249 | Ok(self.iter().cloned()) |
250 | } |
251 | } |
252 | |
253 | #[stable (feature = "rust1" , since = "1.0.0" )] |
254 | impl<T: ToSocketAddrs + ?Sized> ToSocketAddrs for &T { |
255 | type Iter = T::Iter; |
256 | fn to_socket_addrs(&self) -> io::Result<T::Iter> { |
257 | (**self).to_socket_addrs() |
258 | } |
259 | } |
260 | |
261 | #[stable (feature = "string_to_socket_addrs" , since = "1.16.0" )] |
262 | impl ToSocketAddrs for String { |
263 | type Iter = vec::IntoIter<SocketAddr>; |
264 | fn to_socket_addrs(&self) -> io::Result<vec::IntoIter<SocketAddr>> { |
265 | (&**self).to_socket_addrs() |
266 | } |
267 | } |
268 | |