auto merge of #18462 : netvl/rust/to-socket-addr, r=alexcrichton

This is a follow-up to [RFC PR #173](rust-lang/rfcs#173). I was told there that changes like this don't need to go through the RFC process, so I'm submitting this directly.

This PR introduces `ToSocketAddr` trait as defined in said RFC. This trait defines a conversion from different types like `&str`, `(&str, u16)` or even `SocketAddr` to `SocketAddr`. Then this trait is used in all constructor methods for `TcpStream`, `TcpListener` and `UdpSocket`.

This unifies these constructor methods - previously they were using different types of input parameters (TCP ones used `(&str, u16)` pair while UDP ones used `SocketAddr`), which is not consistent by itself and sometimes inconvenient - for example, when the address initially is available as `SocketAddr`, you still need to convert it to string to pass it to e.g. `TcpStream`. This is very prominently demonstrated by the unit tests for TCP functionality. This PR makes working with network objects much like with `Path`, which also uses similar trait to be able to be constructed from `&[u8]`, `Vec<u8>` and other `Path`s.

This is a breaking change. If constant literals were used before, like this:
```rust
TcpStream::connect("localhost", 12345)
```
then the nicest fix is to change it to this:
```rust
TcpStream::connect("localhost:12345")
```

If variables were used before, like this:
```rust
TcpStream::connect(some_address, some_port)
```
then the arguments should be wrapped in another set of parentheses:
```rust
TcpStream::connect((some_address, some_port))
```

`UdpSocket` usages won't break because its constructor method accepted `SocketAddr` which implements `ToSocketAddr`, so `bind()` calls:
```rust
UdpSocket::bind(some_socket_addr)
```
will continue working as before.

I haven't changed `UdpStream` constructor because it is deprecated anyway.

Author: bors

src/compiletest/runtest.rs

@@ -444,7 +444,7 @@ fn run_debuginfo_gdb_test(config: &Config, props: &TestProps, testfile: &Path) {
                 //waiting 1 second for gdbserver start
                 timer::sleep(Duration::milliseconds(1000));
                 let result = task::try(proc() {
-                    tcp::TcpStream::connect("127.0.0.1", 5039).unwrap();
+                    tcp::TcpStream::connect("127.0.0.1:5039").unwrap();
                 });
                 if result.is_err() {
                     continue;

src/libstd/io/mod.rs

@@ -91,7 +91,7 @@ Some examples of obvious things you might want to do
     # // locally, we still want to be type checking this code, so lets
     # // just stop it running (#11576)
     # if false {
-    let mut socket = TcpStream::connect("127.0.0.1", 8080).unwrap();
+    let mut socket = TcpStream::connect("127.0.0.1:8080").unwrap();
     socket.write(b"GET / HTTP/1.0\n\n");
     let response = socket.read_to_end();
     # }
@@ -106,7 +106,7 @@ Some examples of obvious things you might want to do
     use std::io::{TcpListener, TcpStream};
     use std::io::{Acceptor, Listener};
 
-    let listener = TcpListener::bind("127.0.0.1", 80);
+    let listener = TcpListener::bind("127.0.0.1:80");
 
     // bind the listener to the specified address
     let mut acceptor = listener.listen();

src/libstd/io/net/ip.rs

@@ -17,10 +17,14 @@
 
 use fmt;
 use from_str::FromStr;
+use io::{mod, IoResult, IoError};
+use io::net;
 use iter::Iterator;
 use option::{Option, None, Some};
+use result::{Ok, Err};
 use str::StrSlice;
 use slice::{MutableCloneableSlice, MutableSlice, ImmutableSlice};
+use vec::Vec;
 
 pub type Port = u16;
 
@@ -348,6 +352,189 @@ impl FromStr for SocketAddr {
     }
 }
 
+/// A trait for objects which can be converted or resolved to one or more `SocketAddr` values.
+///
+/// Implementing types minimally have to implement either `to_socket_addr` or `to_socket_addr_all`
+/// method, and its trivial counterpart will be available automatically.
+///
+/// This trait is used for generic address resolution when constructing network objects.
+/// By default it is implemented for the following types:
+///
+///  * `SocketAddr` - `to_socket_addr` is identity function.
+///
+///  * `(IpAddr, u16)` - `to_socket_addr` constructs `SocketAddr` trivially.
+///
+///  * `(&str, u16)` - the string should be either a string representation of an IP address
+///    expected by `FromStr` implementation for `IpAddr` or a host name.
+///
+///    For the former, `to_socket_addr_all` returns a vector with a single element corresponding
+///    to that IP address joined with the given port.
+///
+///    For the latter, it tries to resolve the host name and returns a vector of all IP addresses
+///    for the host name, each joined with the given port.
+///
+///  * `&str` - the string should be either a string representation of a `SocketAddr` as
+///    expected by its `FromStr` implementation or a string like `<host_name>:<port>` pair
+///    where `<port>` is a `u16` value.
+///
+///    For the former, `to_socker_addr_all` returns a vector with a single element corresponding
+///    to that socker address.
+///
+///    For the latter, it tries to resolve the host name and returns a vector of all IP addresses
+///    for the host name, each joined with the port.
+///
+///
+/// This trait allows constructing network objects like `TcpStream` or `UdpSocket` easily with
+/// values of various types for the bind/connection address. It is needed because sometimes
+/// one type is more appropriate than the other: for simple uses a string like `"localhost:12345"`
+/// is much nicer than manual construction of the corresponding `SocketAddr`, but sometimes
+/// `SocketAddr` value is *the* main source of the address, and converting it to some other type
+/// (e.g. a string) just for it to be converted back to `SocketAddr` in constructor methods
+/// is pointless.
+///
+/// Some examples:
+///
+/// ```rust,no_run
+/// # #![allow(unused_must_use)]
+///
+/// use std::io::{TcpStream, TcpListener};
+/// use std::io::net::udp::UdpSocket;
+/// use std::io::net::ip::{Ipv4Addr, SocketAddr};
+///
+/// fn main() {
+///     // The following lines are equivalent modulo possible "localhost" name resolution
+///     // differences
+///     let tcp_s = TcpStream::connect(SocketAddr { ip: Ipv4Addr(127, 0, 0, 1), port: 12345 });
+///     let tcp_s = TcpStream::connect((Ipv4Addr(127, 0, 0, 1), 12345u16));
+///     let tcp_s = TcpStream::connect(("127.0.0.1", 12345u16));
+///     let tcp_s = TcpStream::connect(("localhost", 12345u16));
+///     let tcp_s = TcpStream::connect("127.0.0.1:12345");
+///     let tcp_s = TcpStream::connect("localhost:12345");
+///
+///     // TcpListener::bind(), UdpSocket::bind() and UdpSocket::send_to() behave similarly
+///     let tcp_l = TcpListener::bind("localhost:12345");
+///
+///     let mut udp_s = UdpSocket::bind(("127.0.0.1", 23451u16)).unwrap();
+///     udp_s.send_to([7u8, 7u8, 7u8].as_slice(), (Ipv4Addr(127, 0, 0, 1), 23451u16));
+/// }
+/// ```
+pub trait ToSocketAddr {
+    /// Converts this object to single socket address value.
+    ///
+    /// If more than one value is available, this method returns the first one. If no
+    /// values are available, this method returns an `IoError`.
+    ///
+    /// By default this method delegates to `to_socket_addr_all` method, taking the first
+    /// item from its result.
+    fn to_socket_addr(&self) -> IoResult<SocketAddr> {
+        self.to_socket_addr_all()
+            .and_then(|v| v.into_iter().next().ok_or_else(|| IoError {
+                kind: io::InvalidInput,
+                desc: "no address available",
+                detail: None
+            }))
+    }
+
+    /// Converts this object to all available socket address values.
+    ///
+    /// Some values like host name string naturally corrrespond to multiple IP addresses.
+    /// This method tries to return all available addresses corresponding to this object.
+    ///
+    /// By default this method delegates to `to_socket_addr` method, creating a singleton
+    /// vector from its result.
+    #[inline]
+    fn to_socket_addr_all(&self) -> IoResult<Vec<SocketAddr>> {
+        self.to_socket_addr().map(|a| vec![a])
+    }
+}
+
+impl ToSocketAddr for SocketAddr {
+    #[inline]
+    fn to_socket_addr(&self) -> IoResult<SocketAddr> { Ok(*self) }
+}
+
+impl ToSocketAddr for (IpAddr, u16) {
+    #[inline]
+    fn to_socket_addr(&self) -> IoResult<SocketAddr> {
+        let (ip, port) = *self;
+        Ok(SocketAddr { ip: ip, port: port })
+    }
+}
+
+fn resolve_socket_addr(s: &str, p: u16) -> IoResult<Vec<SocketAddr>> {
+    net::get_host_addresses(s)
+        .map(|v| v.into_iter().map(|a| SocketAddr { ip: a, port: p }).collect())
+}
+
+fn parse_and_resolve_socket_addr(s: &str) -> IoResult<Vec<SocketAddr>> {
+    macro_rules! try_opt(
+        ($e:expr, $msg:expr) => (
+            match $e {
+                Some(r) => r,
+                None => return Err(IoError {
+                    kind: io::InvalidInput,
+                    desc: $msg,
+                    detail: None
+                })
+            }
+        )
+    )
+
+    // split the string by ':' and convert the second part to u16
+    let mut parts_iter = s.rsplitn(2, ':');
+    let port_str = try_opt!(parts_iter.next(), "invalid socket address");
+    let host = try_opt!(parts_iter.next(), "invalid socket address");
+    let port: u16 = try_opt!(FromStr::from_str(port_str), "invalid port value");
+    resolve_socket_addr(host, port)
+}
+
+impl<'a> ToSocketAddr for (&'a str, u16) {
+    fn to_socket_addr_all(&self) -> IoResult<Vec<SocketAddr>> {
+        let (host, port) = *self;
+
+        // try to parse the host as a regular IpAddr first
+        match FromStr::from_str(host) {
+            Some(addr) => return Ok(vec![SocketAddr {
+                ip: addr,
+                port: port
+            }]),
+            None => {}
+        }
+
+        resolve_socket_addr(host, port)
+    }
+}
+
+// accepts strings like 'localhost:12345'
+impl<'a> ToSocketAddr for &'a str {
+    fn to_socket_addr(&self) -> IoResult<SocketAddr> {
+        // try to parse as a regular SocketAddr first
+        match FromStr::from_str(*self) {
+            Some(addr) => return Ok(addr),
+            None => {}
+        }
+
+        parse_and_resolve_socket_addr(*self)
+            .and_then(|v| v.into_iter().next()
+                .ok_or_else(|| IoError {
+                    kind: io::InvalidInput,
+                    desc: "no address available",
+                    detail: None
+                })
+            )
+    }
+
+    fn to_socket_addr_all(&self) -> IoResult<Vec<SocketAddr>> {
+        // try to parse as a regular SocketAddr first
+        match FromStr::from_str(*self) {
+            Some(addr) => return Ok(vec![addr]),
+            None => {}
+        }
+
+        parse_and_resolve_socket_addr(*self)
+    }
+}
+
 
 #[cfg(test)]
 mod test {
@@ -457,4 +644,48 @@ mod test {
         assert_eq!(Ipv6Addr(8, 9, 10, 11, 12, 13, 14, 15).to_string(),
                    "8:9:a:b:c:d:e:f".to_string());
     }
+
+    #[test]
+    fn to_socket_addr_socketaddr() {
+        let a = SocketAddr { ip: Ipv4Addr(77, 88, 21, 11), port: 12345 };
+        assert_eq!(Ok(a), a.to_socket_addr());
+        assert_eq!(Ok(vec![a]), a.to_socket_addr_all());
+    }
+
+    #[test]
+    fn to_socket_addr_ipaddr_u16() {
+        let a = Ipv4Addr(77, 88, 21, 11);
+        let p = 12345u16;
+        let e = SocketAddr { ip: a, port: p };
+        assert_eq!(Ok(e), (a, p).to_socket_addr());
+        assert_eq!(Ok(vec![e]), (a, p).to_socket_addr_all());
+    }
+
+    #[test]
+    fn to_socket_addr_str_u16() {
+        let a = SocketAddr { ip: Ipv4Addr(77, 88, 21, 11), port: 24352 };
+        assert_eq!(Ok(a), ("77.88.21.11", 24352u16).to_socket_addr());
+        assert_eq!(Ok(vec![a]), ("77.88.21.11", 24352u16).to_socket_addr_all());
+
+        let a = SocketAddr { ip: Ipv6Addr(0x2a02, 0x6b8, 0, 1, 0, 0, 0, 1), port: 53 };
+        assert_eq!(Ok(a), ("2a02:6b8:0:1::1", 53).to_socket_addr());
+        assert_eq!(Ok(vec![a]), ("2a02:6b8:0:1::1", 53).to_socket_addr_all());
+
+        let a = SocketAddr { ip: Ipv4Addr(127, 0, 0, 1), port: 23924 };
+        assert!(("localhost", 23924u16).to_socket_addr_all().unwrap().contains(&a));
+    }
+
+    #[test]
+    fn to_socket_addr_str() {
+        let a = SocketAddr { ip: Ipv4Addr(77, 88, 21, 11), port: 24352 };
+        assert_eq!(Ok(a), "77.88.21.11:24352".to_socket_addr());
+        assert_eq!(Ok(vec![a]), "77.88.21.11:24352".to_socket_addr_all());
+
+        let a = SocketAddr { ip: Ipv6Addr(0x2a02, 0x6b8, 0, 1, 0, 0, 0, 1), port: 53 };
+        assert_eq!(Ok(a), "[2a02:6b8:0:1::1]:53".to_socket_addr());
+        assert_eq!(Ok(vec![a]), "[2a02:6b8:0:1::1]:53".to_socket_addr_all());
+
+        let a = SocketAddr { ip: Ipv4Addr(127, 0, 0, 1), port: 23924 };
+        assert!("localhost:23924".to_socket_addr_all().unwrap().contains(&a));
+    }
 }

src/libstd/io/net/mod.rs

@@ -10,8 +10,11 @@
 
 //! Networking I/O
 
+use io::{IoError, IoResult, InvalidInput};
+use option::None;
+use result::{Result, Ok, Err};
 use rt::rtio;
-use self::ip::{Ipv4Addr, Ipv6Addr, IpAddr};
+use self::ip::{Ipv4Addr, Ipv6Addr, IpAddr, SocketAddr, ToSocketAddr};
 
 pub use self::addrinfo::get_host_addresses;
 
@@ -38,3 +41,44 @@ fn from_rtio(ip: rtio::IpAddr) -> IpAddr {
         }
     }
 }
+
+fn with_addresses_io<A: ToSocketAddr, T>(
+    addr: A,
+    action: |&mut rtio::IoFactory, rtio::SocketAddr| -> Result<T, rtio::IoError>
+) -> Result<T, IoError> {
+    const DEFAULT_ERROR: IoError = IoError {
+        kind: InvalidInput,
+        desc: "no addresses found for hostname",
+        detail: None
+    };
+
+    let addresses = try!(addr.to_socket_addr_all());
+    let mut err = DEFAULT_ERROR;
+    for addr in addresses.into_iter() {
+        let addr = rtio::SocketAddr { ip: to_rtio(addr.ip), port: addr.port };
+        match rtio::LocalIo::maybe_raise(|io| action(io, addr)) {
+            Ok(r) => return Ok(r),
+            Err(e) => err = IoError::from_rtio_error(e)
+        }
+    }
+    Err(err)
+}
+
+fn with_addresses<A: ToSocketAddr, T>(addr: A, action: |SocketAddr| -> IoResult<T>)
+    -> IoResult<T> {
+    const DEFAULT_ERROR: IoError = IoError {
+        kind: InvalidInput,
+        desc: "no addresses found for hostname",
+        detail: None
+    };
+
+    let addresses = try!(addr.to_socket_addr_all());
+    let mut err = DEFAULT_ERROR;
+    for addr in addresses.into_iter() {
+        match action(addr) {
+            Ok(r) => return Ok(r),
+            Err(e) => err = e
+        }
+    }
+    Err(err)
+}