core/net/
parser.rs

1//! A private parser implementation of IPv4, IPv6, and socket addresses.
2//!
3//! This module is "publicly exported" through the `FromStr` implementations
4//! below.
5
6use crate::error::Error;
7use crate::fmt;
8use crate::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr, SocketAddrV4, SocketAddrV6};
9use crate::str::FromStr;
10
11trait ReadNumberHelper: Sized {
12    const ZERO: Self;
13    fn checked_mul(&self, other: u32) -> Option<Self>;
14    fn checked_add(&self, other: u32) -> Option<Self>;
15}
16
17macro_rules! impl_helper {
18    ($($t:ty)*) => ($(impl ReadNumberHelper for $t {
19        const ZERO: Self = 0;
20        #[inline]
21        fn checked_mul(&self, other: u32) -> Option<Self> {
22            Self::checked_mul(*self, other.try_into().ok()?)
23        }
24        #[inline]
25        fn checked_add(&self, other: u32) -> Option<Self> {
26            Self::checked_add(*self, other.try_into().ok()?)
27        }
28    })*)
29}
30
31impl_helper! { u8 u16 u32 }
32
33struct Parser<'a> {
34    // Parsing as ASCII, so can use byte array.
35    state: &'a [u8],
36}
37
38impl<'a> Parser<'a> {
39    fn new(input: &'a [u8]) -> Parser<'a> {
40        Parser { state: input }
41    }
42
43    /// Run a parser, and restore the pre-parse state if it fails.
44    fn read_atomically<T, F>(&mut self, inner: F) -> Option<T>
45    where
46        F: FnOnce(&mut Parser<'_>) -> Option<T>,
47    {
48        let state = self.state;
49        let result = inner(self);
50        if result.is_none() {
51            self.state = state;
52        }
53        result
54    }
55
56    /// Run a parser, but fail if the entire input wasn't consumed.
57    /// Doesn't run atomically.
58    fn parse_with<T, F>(&mut self, inner: F, kind: AddrKind) -> Result<T, AddrParseError>
59    where
60        F: FnOnce(&mut Parser<'_>) -> Option<T>,
61    {
62        let result = inner(self);
63        if self.state.is_empty() { result } else { None }.ok_or(AddrParseError(kind))
64    }
65
66    /// Reads the next character from the input
67    fn read_char(&mut self) -> Option<char> {
68        self.state.split_first().map(|(&b, tail)| {
69            self.state = tail;
70            char::from(b)
71        })
72    }
73
74    #[must_use]
75    /// Reads the next character from the input if it matches the target.
76    fn read_given_char(&mut self, target: char) -> Option<()> {
77        self.read_atomically(|p| {
78            p.read_char().and_then(|c| if c == target { Some(()) } else { None })
79        })
80    }
81
82    /// Helper for reading separators in an indexed loop. Reads the separator
83    /// character iff index > 0, then runs the parser. When used in a loop,
84    /// the separator character will only be read on index > 0 (see
85    /// read_ipv4_addr for an example)
86    fn read_separator<T, F>(&mut self, sep: char, index: usize, inner: F) -> Option<T>
87    where
88        F: FnOnce(&mut Parser<'_>) -> Option<T>,
89    {
90        self.read_atomically(move |p| {
91            if index > 0 {
92                p.read_given_char(sep)?;
93            }
94            inner(p)
95        })
96    }
97
98    /// Reads a number off the front of the input in the given radix, stopping at the first
99    /// non-digit character or eof. Fails if the number has more digits than `max_digits`, if there
100    /// is no number, if the number overflows `T`, or if there are leading zeros but
101    /// `allow_zero_prefix` is false.
102    ///
103    /// `max_digits` must be in 1..=6.
104    fn read_radix_max_digits<T: ReadNumberHelper + TryFrom<u32>>(
105        &mut self,
106        radix: u32,
107        max_digits: u32,
108        allow_zero_prefix: bool,
109    ) -> Option<T> {
110        debug_assert!(1 <= max_digits);
111        debug_assert!(max_digits <= 6); // Works for any radix in u32
112        self.read_atomically(|p| {
113            let first = p.read_char()?.to_digit(radix)?;
114            let mut result = first;
115            let mut digit_count = 1;
116
117            while let Some(digit) = p.read_atomically(|p| p.read_char()?.to_digit(radix)) {
118                if digit_count >= max_digits {
119                    return None;
120                }
121                result *= radix;
122                result += digit;
123                digit_count += 1;
124            }
125
126            if !allow_zero_prefix && first == 0 && digit_count > 1 {
127                None
128            } else {
129                result.try_into().ok()
130            }
131        })
132    }
133
134    /// Reads a decimal number off the front of the input, stopping at the first non-digit character
135    /// or eof. Fails if there is no number, or if the number overflows `T`. Allows an arbitrary
136    /// amount of leading zeros.
137    fn read_decimal<T: ReadNumberHelper>(&mut self) -> Option<T> {
138        self.read_atomically(|p| {
139            let first = p.read_char()?.to_digit(10)?;
140            let mut result = T::ZERO.checked_add(first)?;
141
142            while let Some(digit) = p.read_atomically(|p| p.read_char()?.to_digit(10)) {
143                result = result.checked_mul(10)?;
144                result = result.checked_add(digit)?;
145            }
146
147            Some(result)
148        })
149    }
150
151    /// Reads an IPv4 address.
152    fn read_ipv4_addr(&mut self) -> Option<Ipv4Addr> {
153        self.read_atomically(|p| {
154            let mut groups = [0; 4];
155
156            for (i, slot) in groups.iter_mut().enumerate() {
157                *slot = p.read_separator('.', i, |p| {
158                    // Disallow octal number in IP string.
159                    // https://tools.ietf.org/html/rfc6943#section-3.1.1
160                    p.read_radix_max_digits(10, 3, false)
161                })?;
162            }
163
164            Some(groups.into())
165        })
166    }
167
168    /// Reads an IPv6 address.
169    fn read_ipv6_addr(&mut self) -> Option<Ipv6Addr> {
170        /// Read a chunk of an IPv6 address into `groups`. Returns the number
171        /// of groups read, along with a bool indicating if an embedded
172        /// trailing IPv4 address was read. Specifically, read a series of
173        /// colon-separated IPv6 groups (0x0000 - 0xFFFF), with an optional
174        /// trailing embedded IPv4 address.
175        fn read_groups(p: &mut Parser<'_>, groups: &mut [u16]) -> (usize, bool) {
176            let limit = groups.len();
177
178            for (i, slot) in groups.iter_mut().enumerate() {
179                // Try to read a trailing embedded IPv4 address. There must be
180                // at least two groups left.
181                if i < limit - 1 {
182                    let ipv4 = p.read_separator(':', i, |p| p.read_ipv4_addr());
183
184                    if let Some(v4_addr) = ipv4 {
185                        let [one, two, three, four] = v4_addr.octets();
186                        groups[i + 0] = u16::from_be_bytes([one, two]);
187                        groups[i + 1] = u16::from_be_bytes([three, four]);
188                        return (i + 2, true);
189                    }
190                }
191
192                let group = p.read_separator(':', i, |p| p.read_radix_max_digits(16, 4, true));
193
194                match group {
195                    Some(g) => *slot = g,
196                    None => return (i, false),
197                }
198            }
199            (groups.len(), false)
200        }
201
202        self.read_atomically(|p| {
203            // Read the front part of the address; either the whole thing, or up
204            // to the first ::
205            let mut head = [0; 8];
206            let (head_size, head_ipv4) = read_groups(p, &mut head);
207
208            if head_size == 8 {
209                return Some(head.into());
210            }
211
212            // IPv4 part is not allowed before `::`
213            if head_ipv4 {
214                return None;
215            }
216
217            // Read `::` if previous code parsed less than 8 groups.
218            // `::` indicates one or more groups of 16 bits of zeros.
219            p.read_given_char(':')?;
220            p.read_given_char(':')?;
221
222            // Read the back part of the address. The :: must contain at least one
223            // set of zeroes, so our max length is 7.
224            let mut tail = [0; 7];
225            let limit = 8 - (head_size + 1);
226            let (tail_size, _) = read_groups(p, &mut tail[..limit]);
227
228            // Concat the head and tail of the IP address
229            head[(8 - tail_size)..8].copy_from_slice(&tail[..tail_size]);
230
231            Some(head.into())
232        })
233    }
234
235    /// Reads an IP address, either IPv4 or IPv6.
236    fn read_ip_addr(&mut self) -> Option<IpAddr> {
237        self.read_ipv4_addr().map(IpAddr::V4).or_else(move || self.read_ipv6_addr().map(IpAddr::V6))
238    }
239
240    /// Reads a `:` followed by a port in base 10.
241    fn read_port(&mut self) -> Option<u16> {
242        self.read_atomically(|p| {
243            p.read_given_char(':')?;
244            p.read_decimal()
245        })
246    }
247
248    /// Reads a `%` followed by a scope ID in base 10.
249    fn read_scope_id(&mut self) -> Option<u32> {
250        self.read_atomically(|p| {
251            p.read_given_char('%')?;
252            p.read_decimal()
253        })
254    }
255
256    /// Reads an IPv4 address with a port.
257    fn read_socket_addr_v4(&mut self) -> Option<SocketAddrV4> {
258        self.read_atomically(|p| {
259            let ip = p.read_ipv4_addr()?;
260            let port = p.read_port()?;
261            Some(SocketAddrV4::new(ip, port))
262        })
263    }
264
265    /// Reads an IPv6 address with a port.
266    fn read_socket_addr_v6(&mut self) -> Option<SocketAddrV6> {
267        self.read_atomically(|p| {
268            p.read_given_char('[')?;
269            let ip = p.read_ipv6_addr()?;
270            let scope_id = p.read_scope_id().unwrap_or(0);
271            p.read_given_char(']')?;
272
273            let port = p.read_port()?;
274            Some(SocketAddrV6::new(ip, port, 0, scope_id))
275        })
276    }
277
278    /// Reads an IP address with a port.
279    fn read_socket_addr(&mut self) -> Option<SocketAddr> {
280        self.read_socket_addr_v4()
281            .map(SocketAddr::V4)
282            .or_else(|| self.read_socket_addr_v6().map(SocketAddr::V6))
283    }
284}
285
286impl IpAddr {
287    /// Parse an IP address from a slice of bytes.
288    ///
289    /// ```
290    /// #![feature(addr_parse_ascii)]
291    ///
292    /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
293    ///
294    /// let localhost_v4 = IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1));
295    /// let localhost_v6 = IpAddr::V6(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1));
296    ///
297    /// assert_eq!(IpAddr::parse_ascii(b"127.0.0.1"), Ok(localhost_v4));
298    /// assert_eq!(IpAddr::parse_ascii(b"::1"), Ok(localhost_v6));
299    /// ```
300    #[unstable(feature = "addr_parse_ascii", issue = "101035")]
301    pub fn parse_ascii(b: &[u8]) -> Result<Self, AddrParseError> {
302        Parser::new(b).parse_with(|p| p.read_ip_addr(), AddrKind::Ip)
303    }
304}
305
306#[stable(feature = "ip_addr", since = "1.7.0")]
307impl FromStr for IpAddr {
308    type Err = AddrParseError;
309    fn from_str(s: &str) -> Result<IpAddr, AddrParseError> {
310        Self::parse_ascii(s.as_bytes())
311    }
312}
313
314impl Ipv4Addr {
315    /// Parse an IPv4 address from a slice of bytes.
316    ///
317    /// ```
318    /// #![feature(addr_parse_ascii)]
319    ///
320    /// use std::net::Ipv4Addr;
321    ///
322    /// let localhost = Ipv4Addr::new(127, 0, 0, 1);
323    ///
324    /// assert_eq!(Ipv4Addr::parse_ascii(b"127.0.0.1"), Ok(localhost));
325    /// ```
326    #[unstable(feature = "addr_parse_ascii", issue = "101035")]
327    pub fn parse_ascii(b: &[u8]) -> Result<Self, AddrParseError> {
328        // don't try to parse if too long
329        if b.len() > 15 {
330            Err(AddrParseError(AddrKind::Ipv4))
331        } else {
332            Parser::new(b).parse_with(|p| p.read_ipv4_addr(), AddrKind::Ipv4)
333        }
334    }
335}
336
337#[stable(feature = "rust1", since = "1.0.0")]
338impl FromStr for Ipv4Addr {
339    type Err = AddrParseError;
340    fn from_str(s: &str) -> Result<Ipv4Addr, AddrParseError> {
341        Self::parse_ascii(s.as_bytes())
342    }
343}
344
345impl Ipv6Addr {
346    /// Parse an IPv6 address from a slice of bytes.
347    ///
348    /// ```
349    /// #![feature(addr_parse_ascii)]
350    ///
351    /// use std::net::Ipv6Addr;
352    ///
353    /// let localhost = Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1);
354    ///
355    /// assert_eq!(Ipv6Addr::parse_ascii(b"::1"), Ok(localhost));
356    /// ```
357    #[unstable(feature = "addr_parse_ascii", issue = "101035")]
358    pub fn parse_ascii(b: &[u8]) -> Result<Self, AddrParseError> {
359        Parser::new(b).parse_with(|p| p.read_ipv6_addr(), AddrKind::Ipv6)
360    }
361}
362
363#[stable(feature = "rust1", since = "1.0.0")]
364impl FromStr for Ipv6Addr {
365    type Err = AddrParseError;
366    fn from_str(s: &str) -> Result<Ipv6Addr, AddrParseError> {
367        Self::parse_ascii(s.as_bytes())
368    }
369}
370
371impl SocketAddrV4 {
372    /// Parse an IPv4 socket address from a slice of bytes.
373    ///
374    /// ```
375    /// #![feature(addr_parse_ascii)]
376    ///
377    /// use std::net::{Ipv4Addr, SocketAddrV4};
378    ///
379    /// let socket = SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 8080);
380    ///
381    /// assert_eq!(SocketAddrV4::parse_ascii(b"127.0.0.1:8080"), Ok(socket));
382    /// ```
383    #[unstable(feature = "addr_parse_ascii", issue = "101035")]
384    pub fn parse_ascii(b: &[u8]) -> Result<Self, AddrParseError> {
385        Parser::new(b).parse_with(|p| p.read_socket_addr_v4(), AddrKind::SocketV4)
386    }
387}
388
389#[stable(feature = "socket_addr_from_str", since = "1.5.0")]
390impl FromStr for SocketAddrV4 {
391    type Err = AddrParseError;
392    fn from_str(s: &str) -> Result<SocketAddrV4, AddrParseError> {
393        Self::parse_ascii(s.as_bytes())
394    }
395}
396
397impl SocketAddrV6 {
398    /// Parse an IPv6 socket address from a slice of bytes.
399    ///
400    /// ```
401    /// #![feature(addr_parse_ascii)]
402    ///
403    /// use std::net::{Ipv6Addr, SocketAddrV6};
404    ///
405    /// let socket = SocketAddrV6::new(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 1), 8080, 0, 0);
406    ///
407    /// assert_eq!(SocketAddrV6::parse_ascii(b"[2001:db8::1]:8080"), Ok(socket));
408    /// ```
409    #[unstable(feature = "addr_parse_ascii", issue = "101035")]
410    pub fn parse_ascii(b: &[u8]) -> Result<Self, AddrParseError> {
411        Parser::new(b).parse_with(|p| p.read_socket_addr_v6(), AddrKind::SocketV6)
412    }
413}
414
415#[stable(feature = "socket_addr_from_str", since = "1.5.0")]
416impl FromStr for SocketAddrV6 {
417    type Err = AddrParseError;
418    fn from_str(s: &str) -> Result<SocketAddrV6, AddrParseError> {
419        Self::parse_ascii(s.as_bytes())
420    }
421}
422
423impl SocketAddr {
424    /// Parse a socket address from a slice of bytes.
425    ///
426    /// ```
427    /// #![feature(addr_parse_ascii)]
428    ///
429    /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr};
430    ///
431    /// let socket_v4 = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), 8080);
432    /// let socket_v6 = SocketAddr::new(IpAddr::V6(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1)), 8080);
433    ///
434    /// assert_eq!(SocketAddr::parse_ascii(b"127.0.0.1:8080"), Ok(socket_v4));
435    /// assert_eq!(SocketAddr::parse_ascii(b"[::1]:8080"), Ok(socket_v6));
436    /// ```
437    #[unstable(feature = "addr_parse_ascii", issue = "101035")]
438    pub fn parse_ascii(b: &[u8]) -> Result<Self, AddrParseError> {
439        Parser::new(b).parse_with(|p| p.read_socket_addr(), AddrKind::Socket)
440    }
441}
442
443#[stable(feature = "rust1", since = "1.0.0")]
444impl FromStr for SocketAddr {
445    type Err = AddrParseError;
446    fn from_str(s: &str) -> Result<SocketAddr, AddrParseError> {
447        Self::parse_ascii(s.as_bytes())
448    }
449}
450
451#[derive(Debug, Clone, PartialEq, Eq)]
452enum AddrKind {
453    Ip,
454    Ipv4,
455    Ipv6,
456    Socket,
457    SocketV4,
458    SocketV6,
459}
460
461/// An error which can be returned when parsing an IP address or a socket address.
462///
463/// This error is used as the error type for the [`FromStr`] implementation for
464/// [`IpAddr`], [`Ipv4Addr`], [`Ipv6Addr`], [`SocketAddr`], [`SocketAddrV4`], and
465/// [`SocketAddrV6`].
466///
467/// # Potential causes
468///
469/// `AddrParseError` may be thrown because the provided string does not parse as the given type,
470/// often because it includes information only handled by a different address type.
471///
472/// ```should_panic
473/// use std::net::IpAddr;
474/// let _foo: IpAddr = "127.0.0.1:8080".parse().expect("Cannot handle the socket port");
475/// ```
476///
477/// [`IpAddr`] doesn't handle the port. Use [`SocketAddr`] instead.
478///
479/// ```
480/// use std::net::SocketAddr;
481///
482/// // No problem, the `panic!` message has disappeared.
483/// let _foo: SocketAddr = "127.0.0.1:8080".parse().expect("unreachable panic");
484/// ```
485#[stable(feature = "rust1", since = "1.0.0")]
486#[derive(Debug, Clone, PartialEq, Eq)]
487pub struct AddrParseError(AddrKind);
488
489#[stable(feature = "addr_parse_error_error", since = "1.4.0")]
490impl fmt::Display for AddrParseError {
491    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
492        match self.0 {
493            AddrKind::Ip => "invalid IP address syntax",
494            AddrKind::Ipv4 => "invalid IPv4 address syntax",
495            AddrKind::Ipv6 => "invalid IPv6 address syntax",
496            AddrKind::Socket => "invalid socket address syntax",
497            AddrKind::SocketV4 => "invalid IPv4 socket address syntax",
498            AddrKind::SocketV6 => "invalid IPv6 socket address syntax",
499        }
500        .fmt(f)
501    }
502}
503
504#[stable(feature = "addr_parse_error_error", since = "1.4.0")]
505impl Error for AddrParseError {}
core/net/parser.rs

core/net/
parser.rs
