tor_general_addr/
general.rs

Help
1//! Support for generalized addresses.
2//!
3//! We use the [`SocketAddr`] type in this module,
4//! when we want write code
5//! that can treat AF_UNIX addresses and internet addresses as a single type.
6//!
7//! As an alternative, you could also write your code to be generic
8//! over address, listener, provider, and stream types.
9//! That would give you the performance benefits of monomorphization
10//! over some corresponding costs in complexity and code size.
11//! Generally, it's better to use these types unless you know
12//! that the minor performance overhead here will matter in practice.
13
14use std::path::Path;
15use std::sync::Arc;
16
17use crate::unix;
18use std::{io::Error as IoError, net};
19
20#[cfg(target_os = "android")]
21use std::os::android::net::SocketAddrExt as _;
22#[cfg(target_os = "linux")]
23use std::os::linux::net::SocketAddrExt as _;
24
25/// Any address that Arti can listen on or connect to.
26///
27/// We use this type when we want to make streams
28/// without being concerned whether they are AF_UNIX streams, TCP streams, or so forth.
29///
30/// To avoid confusion, you might want to avoid importing this type directly.
31/// Instead, import [`rtcompat::general`](crate::general)
32/// and refer to this type as `general::SocketAddr`.
33///
34/// ## String representation
35///
36/// Any `general::SocketAddr` has up to two string representations:
37///
38/// 1. A _qualified_ representation, consisting of a schema
39///    (either "unix" or "inet"),
40///    followed by a single colon,
41///    followed by the address itself represented as a string.
42///
43///    Examples: `unix:/path/to/socket`, `inet:127.0.0.1:9999`,
44///    `inet:[::1]:9999`.
45///
46///    The "unnamed" AF_UNIX address is represented as `unix:`.
47///
48/// 2. A _unqualified_ representation,
49///    consisting of a `net::SocketAddr` address represented as a string.
50///
51///    Examples: `127.0.0.1:9999`,  `[::1]:9999`.
52///
53/// Note that not every `general::SocketAddr` has a string representation!
54/// Currently, the ones that might not be representable are:
55///
56///  - "Abstract" AF_UNIX addresses (a Linux feature)
57///  - AF_UNIX addresses whose path name is not UTF-8.
58///
59/// Note also that string representations may contain whitespace
60/// or other unusual characters.
61/// `/var/run/arti socket` is a valid filename,
62/// so `unix:/var/run/arti socket` is a valid representation.
63///
64/// We may add new schemas in the future.
65/// If we do, any new schema will begin with an ascii alphabetical character,
66/// and will consist only of ascii alphanumeric characters,
67/// the character `-`, and the character `_`.
68///
69/// ### Network address representation
70///
71/// When representing a `net::Socketaddr` address as a string,
72/// we use the formats implemented by [`std::net::SocketAddr`]'s
73/// `FromStr` implementation.  In contrast with the textual representations of
74/// [`Ipv4Addr`](std::net::Ipv4Addr) and [`Ipv6Addr`](std::net::Ipv6Addr),
75/// these formats are not currently very well specified by Rust.
76/// Therefore we describe them here:
77///   * A `SocketAddrV4` is encoded as:
78///     - an [IPv4 address],
79///     - a colon (`:`),
80///     - a 16-bit decimal integer.
81///   * A `SocketAddrV6` is encoded as:
82///     - a left square bracket (`[`),
83///     - an [IPv6 address],
84///     - optionally, a percent sign (`%`) and a 32-bit decimal integer
85///     - a right square bracket (`]`),
86///     - a colon (`:`),
87///     - a 16-bit decimal integer.
88///
89/// Note that the above implementation does not provide any way
90/// to encode the [`flowinfo`](std::net::SocketAddrV6::flowinfo) member
91/// of a `SocketAddrV6`.
92/// Any `flowinfo` information set in an address
93/// will therefore be lost when the address is encoded.
94///
95/// [IPv4 address]: https://doc.rust-lang.org/std/net/struct.Ipv4Addr.html#textual-representation
96/// [IPv6 address]: https://doc.rust-lang.org/std/net/struct.Ipv6Addr.html#textual-representation
97///
98/// TODO: We should try to get Rust's stdlib specify these formats, so we don't have to.
99/// There is an open PR at <https://github.com/rust-lang/rust/pull/131790>.
100#[derive(Clone, Debug, derive_more::From, derive_more::TryInto)]
101#[non_exhaustive]
102pub enum SocketAddr {
103    /// An IPv4 or IPv6 address on the internet.
104    Inet(net::SocketAddr),
105    /// A local AF_UNIX address.
106    ///
107    /// (Note that [`unix::SocketAddr`] is unconstructable on platforms where it is not supported.)
108    Unix(unix::SocketAddr),
109}
110
111impl SocketAddr {
112    /// Return a wrapper object that can be used to display this address.
113    ///
114    /// The resulting display might be lossy, depending on whether this address can be represented
115    /// as a string.
116    ///
117    /// The displayed format here is intentionally undocumented;
118    /// it may change in the future.
119    pub fn display_lossy(&self) -> DisplayLossy<'_> {
120        DisplayLossy(self)
121    }
122
123    /// If possible, return a qualified string representation for this address.
124    ///
125    /// Otherwise return None.
126    pub fn try_to_string(&self) -> Option<String> {
127        use SocketAddr::*;
128        match self {
129            Inet(sa) => Some(format!("inet:{}", sa)),
130            Unix(sa) => {
131                if sa.is_unnamed() {
132                    Some("unix:".to_string())
133                } else {
134                    sa.as_pathname()
135                        .and_then(Path::to_str)
136                        .map(|p| format!("unix:{}", p))
137                }
138            }
139        }
140    }
141
142    /// If this address has an associated filesystem path,
143    /// return that path.
144    pub fn as_pathname(&self) -> Option<&Path> {
145        match self {
146            SocketAddr::Inet(_) => None,
147            SocketAddr::Unix(socket_addr) => socket_addr.as_pathname(),
148        }
149    }
150}
151
152/// Lossy display for a [`SocketAddr`].
153pub struct DisplayLossy<'a>(&'a SocketAddr);
154
155impl<'a> std::fmt::Display for DisplayLossy<'a> {
156    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
157        use SocketAddr::*;
158        match self.0 {
159            Inet(sa) => write!(f, "inet:{}", sa),
160            Unix(sa) => {
161                if let Some(path) = sa.as_pathname() {
162                    if let Some(path_str) = path.to_str() {
163                        write!(f, "unix:{}", path_str)
164                    } else {
165                        write!(f, "unix:{} [lossy]", path.to_string_lossy())
166                    }
167                } else if sa.is_unnamed() {
168                    write!(f, "unix:")
169                } else {
170                    write!(f, "unix:{:?} [lossy]", sa)
171                }
172            }
173        }
174    }
175}
176
177impl std::str::FromStr for SocketAddr {
178    type Err = AddrParseError;
179
180    fn from_str(s: &str) -> Result<Self, Self::Err> {
181        if s.starts_with(|c: char| (c.is_ascii_digit() || c == '[')) {
182            // This looks like an inet address, and cannot be a qualified address.
183            Ok(s.parse::<net::SocketAddr>()?.into())
184        } else if let Some((schema, remainder)) = s.split_once(':') {
185            match schema {
186                "unix" => Ok(unix::SocketAddr::from_pathname(remainder)?.into()),
187                "inet" => Ok(remainder.parse::<net::SocketAddr>()?.into()),
188                _ => Err(AddrParseError::UnrecognizedSchema(schema.to_string())),
189            }
190        } else {
191            Err(AddrParseError::NoSchema)
192        }
193    }
194}
195
196/// An error encountered while attempting to parse a [`SocketAddr`]
197#[derive(Clone, Debug, thiserror::Error)]
198#[non_exhaustive]
199pub enum AddrParseError {
200    /// Tried to parse an address with an unrecognized schema.
201    #[error("Address schema {0:?} unrecognized")]
202    UnrecognizedSchema(String),
203    /// Tried to parse a non inet-address with no schema.
204    #[error("Address did not look like internet, but had no address schema.")]
205    NoSchema,
206    /// Tried to parse an address as an AF_UNIX address, but failed.
207    #[error("Invalid AF_UNIX address")]
208    InvalidAfUnixAddress(#[source] Arc<IoError>),
209    /// Tried to parse an address as a inet address, but failed.
210    #[error("Invalid internet address")]
211    InvalidInetAddress(#[from] std::net::AddrParseError),
212}
213
214impl From<IoError> for AddrParseError {
215    fn from(e: IoError) -> Self {
216        Self::InvalidAfUnixAddress(Arc::new(e))
217    }
218}
219
220impl PartialEq for SocketAddr {
221    /// Return true if two `SocketAddr`s are equal.
222    ///
223    /// For `Inet` addresses, delegates to `std::net::SocketAddr::eq`.
224    ///
225    /// For `Unix` addresses, treats two addresses as equal if any of the following is true:
226    ///   - Both addresses have the same path.
227    ///   - Both addresses are unnamed.
228    ///   - (Linux only) Both addresses have the same abstract name.
229    ///
230    /// Addresses of different types are always unequal.
231    fn eq(&self, other: &Self) -> bool {
232        match (self, other) {
233            (Self::Inet(l0), Self::Inet(r0)) => l0 == r0,
234            #[cfg(unix)]
235            (Self::Unix(l0), Self::Unix(r0)) => {
236                // Sadly, std::os::unix::net::SocketAddr doesn't implement PartialEq.
237                //
238                // This requires us to make our own, and prevents us from providing Eq.
239                if l0.is_unnamed() && r0.is_unnamed() {
240                    return true;
241                }
242                if let (Some(a), Some(b)) = (l0.as_pathname(), r0.as_pathname()) {
243                    return a == b;
244                }
245                #[cfg(any(target_os = "android", target_os = "linux"))]
246                if let (Some(a), Some(b)) = (l0.as_abstract_name(), r0.as_abstract_name()) {
247                    return a == b;
248                }
249                false
250            }
251            _ => false,
252        }
253    }
254}
255
256#[cfg(feature = "arbitrary")]
257impl<'a> arbitrary::Arbitrary<'a> for SocketAddr {
258    fn arbitrary(u: &mut arbitrary::Unstructured<'a>) -> arbitrary::Result<Self> {
259        /// Simple enumeration to select an address type.
260        #[allow(clippy::missing_docs_in_private_items)]
261        #[derive(arbitrary::Arbitrary)]
262        enum Kind {
263            V4,
264            V6,
265            #[cfg(unix)]
266            Unix,
267            #[cfg(any(target_os = "android", target_os = "linux"))]
268            UnixAbstract,
269        }
270        match u.arbitrary()? {
271            Kind::V4 => Ok(SocketAddr::Inet(
272                net::SocketAddrV4::new(u.arbitrary()?, u.arbitrary()?).into(),
273            )),
274            Kind::V6 => Ok(SocketAddr::Inet(
275                net::SocketAddrV6::new(
276                    u.arbitrary()?,
277                    u.arbitrary()?,
278                    u.arbitrary()?,
279                    u.arbitrary()?,
280                )
281                .into(),
282            )),
283            #[cfg(unix)]
284            Kind::Unix => {
285                let pathname: std::ffi::OsString = u.arbitrary()?;
286                Ok(SocketAddr::Unix(
287                    unix::SocketAddr::from_pathname(pathname)
288                        .map_err(|_| arbitrary::Error::IncorrectFormat)?,
289                ))
290            }
291            #[cfg(any(target_os = "android", target_os = "linux"))]
292            Kind::UnixAbstract => {
293                #[cfg(target_os = "android")]
294                use std::os::android::net::SocketAddrExt as _;
295                #[cfg(target_os = "linux")]
296                use std::os::linux::net::SocketAddrExt as _;
297                let name: &[u8] = u.arbitrary()?;
298                Ok(SocketAddr::Unix(
299                    unix::SocketAddr::from_abstract_name(name)
300                        .map_err(|_| arbitrary::Error::IncorrectFormat)?,
301                ))
302            }
303        }
304    }
305}
306
307#[cfg(test)]
308mod test {
309    // @@ begin test lint list maintained by maint/add_warning @@
310    #![allow(clippy::bool_assert_comparison)]
311    #![allow(clippy::clone_on_copy)]
312    #![allow(clippy::dbg_macro)]
313    #![allow(clippy::mixed_attributes_style)]
314    #![allow(clippy::print_stderr)]
315    #![allow(clippy::print_stdout)]
316    #![allow(clippy::single_char_pattern)]
317    #![allow(clippy::unwrap_used)]
318    #![allow(clippy::unchecked_duration_subtraction)]
319    #![allow(clippy::useless_vec)]
320    #![allow(clippy::needless_pass_by_value)]
321    //! <!-- @@ end test lint list maintained by maint/add_warning @@ -->
322
323    use super::AddrParseError;
324    use crate::general;
325    use assert_matches::assert_matches;
326    #[cfg(unix)]
327    use std::os::unix::net as unix;
328    use std::{net, str::FromStr as _};
329
330    /// Parse `s` as a `net::SocketAddr`, and build a `general::SocketAddr` from it.
331    ///
332    /// Testing only. Panics on error.
333    fn from_inet(s: &str) -> general::SocketAddr {
334        let a: net::SocketAddr = s.parse().unwrap();
335        a.into()
336    }
337
338    #[test]
339    fn ok_inet() {
340        assert_eq!(
341            from_inet("127.0.0.1:9999"),
342            general::SocketAddr::from_str("127.0.0.1:9999").unwrap()
343        );
344        assert_eq!(
345            from_inet("127.0.0.1:9999"),
346            general::SocketAddr::from_str("inet:127.0.0.1:9999").unwrap()
347        );
348
349        assert_eq!(
350            from_inet("[::1]:9999"),
351            general::SocketAddr::from_str("[::1]:9999").unwrap()
352        );
353        assert_eq!(
354            from_inet("[::1]:9999"),
355            general::SocketAddr::from_str("inet:[::1]:9999").unwrap()
356        );
357
358        assert_ne!(
359            general::SocketAddr::from_str("127.0.0.1:9999").unwrap(),
360            general::SocketAddr::from_str("[::1]:9999").unwrap()
361        );
362
363        let ga1 = from_inet("127.0.0.1:9999");
364        assert_eq!(ga1.display_lossy().to_string(), "inet:127.0.0.1:9999");
365        assert_eq!(ga1.try_to_string().unwrap(), "inet:127.0.0.1:9999");
366
367        let ga2 = from_inet("[::1]:9999");
368        assert_eq!(ga2.display_lossy().to_string(), "inet:[::1]:9999");
369        assert_eq!(ga2.try_to_string().unwrap(), "inet:[::1]:9999");
370    }
371
372    /// Treat `s` as a path for an AF_UNIX socket, and build a `general::SocketAddr` from it.
373    ///
374    /// Testing only. Panics on error.
375    #[cfg(unix)]
376    fn from_pathname(s: impl AsRef<std::path::Path>) -> general::SocketAddr {
377        let a = unix::SocketAddr::from_pathname(s).unwrap();
378        a.into()
379    }
380    #[test]
381    #[cfg(unix)]
382    fn ok_unix() {
383        assert_eq!(
384            from_pathname("/some/path"),
385            general::SocketAddr::from_str("unix:/some/path").unwrap()
386        );
387        assert_eq!(
388            from_pathname("/another/path"),
389            general::SocketAddr::from_str("unix:/another/path").unwrap()
390        );
391        assert_eq!(
392            from_pathname("/path/with spaces"),
393            general::SocketAddr::from_str("unix:/path/with spaces").unwrap()
394        );
395        assert_ne!(
396            general::SocketAddr::from_str("unix:/some/path").unwrap(),
397            general::SocketAddr::from_str("unix:/another/path").unwrap()
398        );
399        assert_eq!(
400            from_pathname(""),
401            general::SocketAddr::from_str("unix:").unwrap()
402        );
403
404        let ga1 = general::SocketAddr::from_str("unix:/some/path").unwrap();
405        assert_eq!(ga1.display_lossy().to_string(), "unix:/some/path");
406        assert_eq!(ga1.try_to_string().unwrap(), "unix:/some/path");
407
408        let ga2 = general::SocketAddr::from_str("unix:/another/path").unwrap();
409        assert_eq!(ga2.display_lossy().to_string(), "unix:/another/path");
410        assert_eq!(ga2.try_to_string().unwrap(), "unix:/another/path");
411    }
412
413    #[test]
414    fn parse_err_inet() {
415        assert_matches!(
416            "1234567890:999".parse::<general::SocketAddr>(),
417            Err(AddrParseError::InvalidInetAddress(_))
418        );
419        assert_matches!(
420            "1z".parse::<general::SocketAddr>(),
421            Err(AddrParseError::InvalidInetAddress(_))
422        );
423        assert_matches!(
424            "[[77".parse::<general::SocketAddr>(),
425            Err(AddrParseError::InvalidInetAddress(_))
426        );
427
428        assert_matches!(
429            "inet:fred:9999".parse::<general::SocketAddr>(),
430            Err(AddrParseError::InvalidInetAddress(_))
431        );
432
433        assert_matches!(
434            "inet:127.0.0.1".parse::<general::SocketAddr>(),
435            Err(AddrParseError::InvalidInetAddress(_))
436        );
437
438        assert_matches!(
439            "inet:[::1]".parse::<general::SocketAddr>(),
440            Err(AddrParseError::InvalidInetAddress(_))
441        );
442    }
443
444    #[test]
445    fn parse_err_schemata() {
446        assert_matches!(
447            "fred".parse::<general::SocketAddr>(),
448            Err(AddrParseError::NoSchema)
449        );
450        assert_matches!(
451            "fred:".parse::<general::SocketAddr>(),
452            Err(AddrParseError::UnrecognizedSchema(f)) if f == "fred"
453        );
454        assert_matches!(
455            "fred:hello".parse::<general::SocketAddr>(),
456            Err(AddrParseError::UnrecognizedSchema(f)) if f == "fred"
457        );
458    }
459
460    #[test]
461    #[cfg(unix)]
462    fn display_unix_weird() {
463        use std::ffi::OsStr;
464        use std::os::unix::ffi::OsStrExt as _;
465
466        let a1 = from_pathname(OsStr::from_bytes(&[255, 255, 255, 255]));
467        assert!(a1.try_to_string().is_none());
468        assert_eq!(a1.display_lossy().to_string(), "unix:���� [lossy]");
469
470        let a2 = from_pathname("");
471        assert_eq!(a2.try_to_string().unwrap(), "unix:");
472        assert_eq!(a2.display_lossy().to_string(), "unix:");
473    }
474
475    #[test]
476    #[cfg(not(unix))]
477    fn parse_err_no_unix() {
478        assert_matches!(
479            "unix:".parse::<general::SocketAddr>(),
480            Err(AddrParseError::InvalidAfUnixAddress(_))
481        );
482        assert_matches!(
483            "unix:/any/path".parse::<general::SocketAddr>(),
484            Err(AddrParseError::InvalidAfUnixAddress(_))
485        );
486    }
487}
tor_general_addr/general.rs

tor_general_addr/
general.rs
