use IPV6 loopback and documentation address in documentation over V4 by default

[2ndDerivative]

View all comments

This defaults all documentation unrelated to specific IP versions to the current IPv6.

Related to issue #161832

I didn't touch any tests, as I'm pretty new and don't know much about the test infrastructure, but maybe it should be considered to run all the tests via the v6 loopback by default too.

Feel free to discuss and / or critique!

[rustbot]

Thanks for the pull request, and welcome! The Rust Project has assigned @joboet (or someone else) to review your changes, you should hear from them (or someone else) within the next two weeks.

Please see the contribution instructions and our LLM policy for more information.

Why was this reviewer chosen?

The reviewer was selected based on:

• Owners of files modified in this PR: @ChrisDenton, libs
• @ChrisDenton, libs expanded to 13 candidates
• Random selection from 6 candidates

[rustbot]

⚠️ Warning ⚠️

• There are issue links (such as #123) in the commit messages of the following commits.
  Please move them to the PR description, to avoid spamming the issues with references to the commit, and so this bot can automatically canonicalize them to avoid issues with subtree.
  • 917ee86

[joboet]

I really don't have an opinion here, networking isn't my domain (pun intended).

@rustbot reroll

[ChrisDenton]

I admit I'm struggling to feel strongly about this either way. This does feel like a policy decision though:

I think the Rust docs could be doing their part to normalize using [IPv6].

@rust-lang/libs does anybody have thoughts on this?

[clarfonthey]

I can take this over since I did the previous one. r? clarfonthey

[tgross35]

I think the Rust docs could be doing their part to normalize using [IPv6].

@rust-lang/libs does anybody have thoughts on this?

Personally I'm -0.75 – users are way more likely to encounter IPv4 at the time being, and likely for the foreseeable future. I don't think I've ever seen documentation anywhere use [::1] rather than 127.0.0.1 when both are an option.

[clarfonthey]

This is definitely a spicy take, but I feel compelled to remind people that IPv6 is almost 30 years old and the fact that we still use IPv4 at all is a travesty and something the entire tech industry should be ashamed of.

(Yes, IPv6 was standardised in 1998. It's that old.)

I agree that we should still support IPv4 and make sure that our APIs can handle it, but I think that if people are confused to see IPv6 addresses on APIs that very explicitly accept them that is something they should quickly rectify. And, it's especially helpful that the two most commonly written IPv6 addresses, [::1] and [::], are shorter to type than their IPv4 counterparts, 127.0.0.1 and 0.0.0.0.

I will probably ask around the libs team to make sure I'm not being too spicy here but most of the arguments I've seen complaining about IPv6 (here and elsewhere) are mostly just people misunderstanding how IPv6 works or being resistant to change, neither of which feels particularly compelling here.

[kennytm]

It's especially helpful that the two most commonly written IPv6 addresses, [::1] and [::], are shorter to type than their IPv4 counterparts, 127.0.0.1 and 0.0.0.0.

Disagreed, in a typical keyboard to enter an IPv6 address you need to reach for Shift and requires simultaneous touch. To type ::1 you need Shift+;; → (release Shift) → 1, while the IPv4 localhost you just type 127.0.0.1 directly. It is shorter to type ::1 but not easier than 127.0.0.1.

In any case typing should not be relevant to this PR at all, this PR is about example code i.e. reading, and I'd argue:

1. People recognizes words not individual letters, the strlen of ::1 vs 127.0.0.1 don't impact readability.

2. OTOH, some example code replaced Ipv4Addr::new(127, 0, 0, 1) with Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), or Ipv4Addr::new(10, 10, 0, 1) with Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 1), and the IPv6 counterparts are much harder to read, because you can't take advantage of the compressed representation (::1, 2001:db8::1) in code.

3. Mostly a fault of Rust not supporting optional arguments, the constructor of SocketAddrV6 required filling in flowinfo and scope_id, leading to uncanny changes such as

-   ///            SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 8080)));
+   ///            SocketAddr::V6(SocketAddrV6::new(
+   ///                 Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1),
+   ///                 8080,
+   ///                 0,
+   ///                 0
+   /// )));

I will probably ask around the libs team to make sure I'm not being too spicy here but most of the arguments I've seen complaining about IPv6 (here and elsewhere) are mostly just people misunderstanding how IPv6 works or being resistant to change, neither of which feels particularly compelling here.

While I'd love to see IPv6 supported everywhere (CGNAT is awful), in the context of this PR I don't see replacing examples using 127.0.0.1 with ::1 alone produced any benefits (this is unlike 0.0.0.0:x → [::]:x that the latter enabled IPv6+v4 connectivity on a dual-stack system). There is lack of compelling reason to merge this PR, unless it is part of a grand policy of T-libs as called out above #161879 (comment).

[2ndDerivative]

It's especially helpful that the two most commonly written IPv6 addresses, [::1] and [::], are shorter to type than their IPv4 counterparts, 127.0.0.1 and 0.0.0.0.

Disagreed, in a typical keyboard to enter an IPv6 address you need to reach for Shift and requires simultaneous touch. To type ::1 you need Shift+;; → (release Shift) → 1, while the IPv4 localhost you just type 127.0.0.1 directly. It is shorter to type ::1 but not easier than 127.0.0.1.

In any case typing should not be relevant to this PR at all, this PR is about example code i.e. reading, and I'd argue:

1. People recognizes words not individual letters, the strlen of ::1 vs 127.0.0.1 don't impact readability.

2. OTOH, some example code replaced Ipv4Addr::new(127, 0, 0, 1) with Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), or Ipv4Addr::new(10, 10, 0, 1) with Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 1), and the IPv6 counterparts are much harder to read, because you can't take advantage of the compressed representation (::1, 2001:db8::1) in code.

3. Mostly a fault of Rust not supporting optional arguments, the constructor of SocketAddrV6 required filling in flowinfo and scope_id, leading to uncanny changes such as

-   ///            SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 8080)));
+   ///            SocketAddr::V6(SocketAddrV6::new(
+   ///                 Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1),
+   ///                 8080,
+   ///                 0,
+   ///                 0
+   /// )));

If readability is your problem, we can always replace this kind of usage with the LOCALHOST and UNSPECIFIED constants

[kennytm]

If readability is your problem, we can always replace this kind of usage with the LOCALHOST and UNSPECIFIED constants

1. For LOCALHOST: Sure.

   This PR does not introduce any UNSPECIFIED and you can shorten it with [0_u16; 8] anyway.

   But 2001:db8::1 can't be simplified, you gotta write Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 1) or Ipv6Addr::from_bits(0x2001_0db8_0000_0000_0000_0000_0000_0001) for unwrap-free code.

2. Readability is a response to use IPV6 loopback and documentation address in documentation over V4 by default #161879 (comment) saying some IPv6 addresses are shorter to type. My stance is already described in Documentation examples should default to IPv6 instead of IPv4 #161832 (comment) I'm not gonna copy here.

[clarfonthey]

unless it is part of a grand policy of T-libs as called out above #161879 (comment).

It is explicitly not a grander T-libs policy which is why I've been asking for more explicit feedback on it. While I think this is a better change, I am also someone who kind of wants to bend over backwards to get people more used to IPv6, which is far from a neutral position. And it's also especially worthwhile to call out ergonomics here, which are fixable but require broader changes.

[clarfonthey]

Okay, so, a day later, dismounting my horse, I actually thought the original issue had way more support than it actually did, and also 100% agree that while for APIs like IpAddr this is fair, for other generic APIs there is less perceived benefit. I do think however that the docs are the perfect place to get people more acquainted with IPv6 addresses, since we should do that.

I think it would be reasonable to stop and say that we probably should not explicitly just replace 127.0.0.1 with ::1 here, but I think anywhere where we add both IPv4 and IPv6 examples is fine. I'll point them out as examples in review comments.

Edit: there actually aren't examples of this happening, since I failed tech 101 and that diffs include the before and after because I was excited about IPv6. But alternating between examples might be okay. Would need to generate docs after to compare, but, maybe that's reasonable to have a broader variety of addresses.