Rework `Ipv6Addr::is_global` to check for global reachability rather than global scope #86634

CDirkx · 2021-06-25T20:02:33Z

This PR changes the unstable method Ipv6Addr::is_global to make it consistent with Ipv4Addr::is_global, checking for reachability rather than global scope (see also #85696 fixing this conflation in Ipv6Addr::is_unicast_global).

To summarize, there are two concepts; an address can be globally reachable, and an address can have global scope. These concepts have been conflated in the past, but are not the same thing. There exist addresses with global scope that are not globally reachable (for example unique local addresses), and addresses that are globally reachable without having global scope (multicast addresses with non-global scope). is_unicast_global should be used to check for global scope, and is_global for global reachability according to the IANA IPv6 Special-Purpose Address Registry, like is done in Ipv4Addr::is_global and other language implementations. (To prevent this confusion in the future, #85696 renames is_unicast_global to has_unicast_global_scope)

The documentation of Ipv4Addr::is_global is also updated to make the two methods have similar descriptions and examples.

rust-highfive · 2021-06-25T20:02:36Z

r? @kennytm

(rust-highfive has picked a reviewer for you, use r? to override)

CDirkx · 2021-06-25T20:05:21Z

library/std/src/net/ip.rs

-    /// Returns [`true`] if the address appears to be globally routable.
-    /// See [iana-ipv4-special-registry][ipv4-sr].
-    ///
-    /// The following return [`false`]:
-    ///
-    /// - private addresses (see [`Ipv4Addr::is_private()`])
-    /// - the loopback address (see [`Ipv4Addr::is_loopback()`])
-    /// - the link-local address (see [`Ipv4Addr::is_link_local()`])
-    /// - the broadcast address (see [`Ipv4Addr::is_broadcast()`])
-    /// - addresses used for documentation (see [`Ipv4Addr::is_documentation()`])
-    /// - the unspecified address (see [`Ipv4Addr::is_unspecified()`]), and the whole
-    ///   `0.0.0.0/8` block
-    /// - addresses reserved for future protocols (see
-    /// [`Ipv4Addr::is_ietf_protocol_assignment()`], except
-    /// `192.0.0.9/32` and `192.0.0.10/32` which are globally routable
-    /// - addresses reserved for future use (see [`Ipv4Addr::is_reserved()`]
-    /// - addresses reserved for networking devices benchmarking (see
-    /// [`Ipv4Addr::is_benchmarking()`])
-    ///
-    /// [ipv4-sr]: https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml
+    /// Returns [`true`] if the address appears to be globally reachable
+    /// as specified by the [IANA IPv4 Special-Purpose Address Registry].
+    /// Whether or not an address is practically reachable will depend on your network configuration.
+    ///
+    /// Most IPv4 addresses are globally reachable;
+    /// unless they are specifically defined as *not* globally reachable.
+    ///
+    /// Non-exhaustive list of notable addresses that are not globally reachable:
+    ///
+    /// - The [unspecified address] ([`is_unspecified`](Ipv4Addr::is_unspecified))
+    /// - Addresses reserved for private use ([`is_private`](Ipv4Addr::is_private))
+    /// - Addresses in the shared address space ([`is_shared`](Ipv4Addr::is_shared))
+    /// - Loopback addresses ([`is_loopback`](Ipv4Addr::is_loopback))
+    /// - Link-local addresses ([`is_link_local`](Ipv4Addr::is_link_local))
+    /// - Addresses reserved for documentation ([`is_documentation`](Ipv4Addr::is_documentation))
+    /// - Addresses reserved for benchmarking ([`is_benchmarking`](Ipv4Addr::is_benchmarking))
+    /// - Reserved addresses ([`is_reserved`](Ipv4Addr::is_reserved))
+    /// - The [broadcast address] ([`is_broadcast`](Ipv4Addr::is_broadcast))
+    ///
+    /// For the complete overview of which addresses are globally reachable, see the table at the [IANA IPv4 Special-Purpose Address Registry].


Reworded to a (in my opinion) less cluttered non-exhaustive list. Instead of trying to list every type of address and exceptions, we list the most notable ones (mostly the ones Rust has methods for) and refer to the Special Address Registry for the complete overview. A similar thing is done in the description of Ipv6Addr::is_global.

CDirkx · 2021-06-25T20:05:50Z

library/std/src/net/ip.rs

-        // check if this address is 192.0.0.9 or 192.0.0.10. These addresses are the only two
-        // globally routable addresses in the 192.0.0.0/24 range.
-        if u32::from_be_bytes(self.octets()) == 0xc0000009
-            || u32::from_be_bytes(self.octets()) == 0xc000000a
-        {
-            return true;
-        }
-        !self.is_private()
-            && !self.is_loopback()
-            && !self.is_link_local()
-            && !self.is_broadcast()
-            && !self.is_documentation()
-            && !self.is_shared()
-            && !self.is_ietf_protocol_assignment()
-            && !self.is_reserved()
-            && !self.is_benchmarking()
-            // Make sure the address is not in 0.0.0.0/8
-            && self.octets()[0] != 0
+        !(self.octets()[0] == 0 // "This network"
+            || self.is_private()
+            || self.is_shared()
+            || self.is_loopback()
+            || self.is_link_local()
+            || (self.is_ietf_protocol_assignment()
+                && !(
+                    // Port Control Protocol Anycast (`192.0.0.9`)
+                    u32::from_be_bytes(self.octets()) == 0xc0000009
+                    // Traversal Using Relays around NAT Anycast (`192.0.0.10`)
+                    || u32::from_be_bytes(self.octets()) == 0xc000000a
+                ))
+            || self.is_documentation()
+            || self.is_benchmarking()
+            || self.is_reserved()
+            || self.is_broadcast())


Reordered the checks to match the order in the Special Address Registry.

CDirkx · 2021-06-25T20:06:36Z

library/std/src/net/ip.rs

@@ -1214,13 +1214,33 @@ impl Ipv6Addr {
        u128::from_be_bytes(self.octets()) == u128::from_be_bytes(Ipv6Addr::LOCALHOST.octets())
    }

-    /// Returns [`true`] if the address appears to be globally routable.
+    /// Returns [`true`] if the address appears to be globally reachable


"globally reachable" instead of "globally routable", as that is the terminology used in the Special Address Registry.

CDirkx · 2021-06-25T20:08:47Z

library/std/src/net/ip.rs

-    /// Returns [`true`] if the address appears to be globally routable.
+    /// Returns [`true`] if the address appears to be globally reachable
+    /// as specified by the [IANA IPv6 Special-Purpose Address Registry].
+    /// Whether or not an address is practically reachable will depend on your network configuration.


If you're not connected to the internet, you still can't reach a "globally reachable" address. I hope this also makes it clear that this method doesn't actually do any network traffic.

CDirkx · 2021-06-25T20:10:46Z

library/std/src/net/ip.rs

+    /// Note that an address having global scope is not the same as being globally reachable,
+    /// and there is no direct relation between the two concepts: There exist addresses with global scope
+    /// that are not globally reachable (for example unique local addresses),
+    /// and addresses that are globally reachable without having global scope
+    /// (multicast addresses with non-global scope).


Trying to avoid the confusion between "globally reachable" and "global scope", the rename in #85696 from is_unicast_global to has_unicast_global_scope should hopefully help with this. Another possibility would be to rename is_global to is_globally_reachable.

library/std/src/net/ip.rs

CDirkx · 2021-06-25T20:18:21Z

library/std/src/net/ip/tests.rs

-    check!("ff01::", multicast);
-    check!("ff02::", multicast);
-    check!("ff03::", multicast);
-    check!("ff04::", multicast);
-    check!("ff05::", multicast);
-    check!("ff08::", multicast);
+    check!("ff01::", global | multicast);
+    check!("ff02::", global | multicast);
+    check!("ff03::", global | multicast);
+    check!("ff04::", global | multicast);
+    check!("ff05::", global | multicast);
+    check!("ff08::", global | multicast);


As mentioned in the PR description, multicast addresses with non-global scope are actually still globally reachable.

…n global scope

CDirkx · 2021-07-08T12:37:19Z

Addressed an incorrect check pointed out in #86969 (comment)

bors · 2021-08-02T08:34:15Z

☔ The latest upstream changes (presumably #87535) made this pull request unmergeable. Please resolve the merge conflicts.

…plett Add `Ipv6Addr::is_benchmarking` This PR adds the unstable method `Ipv6Addr::is_benchmarking`. This method is added for parity with `Ipv4Addr::is_benchmarking`, and I intend to use it in a future rework of `Ipv6Addr::is_global` (edit: rust-lang#86634) to more accurately follow the [IANA Special Address Registry](https://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.xhtml) (like is done in `Ipv4Addr::is_global`). With `Ipv6Addr::is_benchmarking` and `Ipv4Addr::is_benchmarking` now both existing, `IpAddr::is_benchmarking` is also added.

JohnCSimon · 2022-04-24T22:14:30Z

Ping from triage:
@kennytm what is the status of this review?

Mark-Simulacrum · 2022-08-21T15:12:18Z

Approved #99957, so going to go ahead and close this PR. #99957 contains the commits from here though.

Thanks!

…se, r=Mark-Simulacrum Rework Ipv6Addr::is_global to check for global reachability rather than global scope - rebase Rebasing of pull request rust-lang#86634 off of master to try and get the feature "ip" stabilized. I also found a test failure in the rebase that is_global was considering the benchmark space to be globally reachable. This is related to my other rebasing pull request rust-lang#99947

rust-highfive assigned kennytm Jun 25, 2021

rustbot added A-io Area: std::io, std::fs, std::net and std::path T-libs-api Relevant to the library API team, which will review and decide on the PR/issue. labels Jun 25, 2021

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jun 25, 2021

CDirkx commented Jun 25, 2021

View reviewed changes

library/std/src/net/ip.rs Show resolved Hide resolved

CDirkx commented Jun 25, 2021

View reviewed changes

CDirkx force-pushed the ip-globally-reachable branch from dabff95 to 2be1e92 Compare July 1, 2021 15:50

CDirkx mentioned this pull request Jul 8, 2021

Introduce private helper method in_network for Ipv{4,6}Addr #86969

Closed

CDirkx added 2 commits July 8, 2021 14:33

Fix Ipv6Addr::is_global to check for global reachability rather tha…

90f8e7a

…n global scope

Change Ipv4Addr::is_global to be in line with Ipv6Addr::is_global

9ddd5a5

CDirkx force-pushed the ip-globally-reachable branch from 2be1e92 to 9ddd5a5 Compare July 8, 2021 12:36

JohnCSimon added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jul 25, 2021

camelid added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Aug 20, 2021

JohnCSimon added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Sep 6, 2021

JohnCSimon added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Sep 27, 2021

JohnCSimon added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Oct 19, 2021

JohnCSimon added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Nov 8, 2021

JohnCSimon added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Dec 5, 2021

JohnCSimon added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Feb 6, 2022

elenaf9 mentioned this pull request Apr 17, 2022

protocols/autonat: optionally use only global IPs libp2p/rust-libp2p#2618

Merged

4 tasks

JohnCSimon added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels May 22, 2022

JohnCSimon added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jun 20, 2022

JohnCSimon added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jul 24, 2022

chotchki mentioned this pull request Jul 30, 2022

Rework Ipv6Addr::is_global to check for global reachability rather than global scope - rebase #99957

Merged

Mark-Simulacrum closed this Aug 21, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Rework `Ipv6Addr::is_global` to check for global reachability rather than global scope #86634

Rework `Ipv6Addr::is_global` to check for global reachability rather than global scope #86634

CDirkx commented Jun 25, 2021 •

edited

Loading

rust-highfive commented Jun 25, 2021

CDirkx Jun 25, 2021 •

edited

Loading

CDirkx Jun 25, 2021

CDirkx Jun 25, 2021

CDirkx Jun 25, 2021

CDirkx Jun 25, 2021

CDirkx Jun 25, 2021 •

edited

Loading

CDirkx commented Jul 8, 2021

bors commented Aug 2, 2021

JohnCSimon commented Apr 24, 2022

Mark-Simulacrum commented Aug 21, 2022

Rework Ipv6Addr::is_global to check for global reachability rather than global scope #86634

Rework Ipv6Addr::is_global to check for global reachability rather than global scope #86634

Conversation

CDirkx commented Jun 25, 2021 • edited Loading

rust-highfive commented Jun 25, 2021

CDirkx Jun 25, 2021 • edited Loading

Choose a reason for hiding this comment

CDirkx Jun 25, 2021

Choose a reason for hiding this comment

CDirkx Jun 25, 2021

Choose a reason for hiding this comment

CDirkx Jun 25, 2021

Choose a reason for hiding this comment

CDirkx Jun 25, 2021

Choose a reason for hiding this comment

CDirkx Jun 25, 2021 • edited Loading

Choose a reason for hiding this comment

CDirkx commented Jul 8, 2021

bors commented Aug 2, 2021

JohnCSimon commented Apr 24, 2022

Mark-Simulacrum commented Aug 21, 2022

Rework `Ipv6Addr::is_global` to check for global reachability rather than global scope #86634

Rework `Ipv6Addr::is_global` to check for global reachability rather than global scope #86634

CDirkx commented Jun 25, 2021 •

edited

Loading

CDirkx Jun 25, 2021 •

edited

Loading

CDirkx Jun 25, 2021 •

edited

Loading