Stabilize Ipv6Addr::is_unique_local and Ipv6Addr::is_unicast_link_local

[umgefahren]

Make Ipv6Addr::is_unique_local and Ipv6Addr::is_unicast_link_local stable (+const).

Newly stable API:

impl Ipv6Addr {
	// Newly stable under `ipv6_is_unique_local`
	const fn is_unique_local(&self) -> bool;

	// Newly stable under `ipv6_is_unique_local`
	const fn is_unicast_link_local(&self) -> bool;
}

These stabilise a subset of the following tracking issue:

• Tracking issue for Ipv{4,6}Addr convenience methods #27709

I have looked and could not find any issues with is_unique_local and is_unicast_link_local. There is a well received comment calling for stabilisation of the latter function.

Both functions are well defined and consistent with implementations in other languages:

• Go
• Python
• Ruby (unique local)
• Ruby (unicast link local)

cc implementor @little-dude
(I can't find the original PR for is_unqiue_local)

r? libs-api
@rustbot label +T-libs-api +needs-fcp

[rustbot]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @joshtriplett (or someone else) some time within the next two weeks.

Please see the contribution instructions for more information. Namely, in order to ensure the minimum review times lag, PR authors and assigned reviewers should ensure that the review label (S-waiting-on-review and S-waiting-on-author) stays updated, invoking these commands when appropriate:

• @rustbot author: the review is finished, PR author should check the comments and take action accordingly
• @rustbot review: the author is ready for a review, this PR will be queued again in the reviewer's queue

[umgefahren]

r? dtolnay

Since @dtolnay reviewed the last stabilisation PR in this domain.

[rustbot]

Failed to set assignee to dtolney: invalid assignee

Note: Only org members with at least the repository "read" role, users with write permissions, or people who have commented on the PR may be assigned.

[dtolnay]

Both functions are well defined and consistent with implementations in other languages:

• Go

This one isn't entirely true. (I didn't try any of the other languages.)

Rust: https://play.rust-lang.org/?version=nightly&mode=debug&edition=2021&gist=6770cd0cf0a2e5439580dfaf5bf41471

#![feature(ip)]

fn main() {
    let ip = std::net::Ipv6Addr::from([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 255, 255, 169, 254, 0, 0]);
    println!("{} {}", ip, ip.is_unicast_link_local());
}

::ffff:169.254.0.0 false

Go: https://go.dev/play/p/b4E92eet5Yg

package main

import (
    "fmt"
    "net/netip"
)

func main() {
    ip := netip.AddrFrom16([16]byte{0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 255, 255, 169, 254, 0, 0})
    fmt.Println(ip, ip.IsLinkLocalUnicast())
}

::ffff:169.254.0.0 true

The difference comes down to this "not assigned any special meaning", which is not the case in Go:

rust/library/core/src/net/ip_addr.rs

Lines 98 to 104 in 804be74

	/// To assist in the transition from IPv4 to IPv6 two types of IPv6 addresses that embed an IPv4 address were defined:
	/// IPv4-compatible and IPv4-mapped addresses. Of these IPv4-compatible addresses have been officially deprecated.
	///
	/// Both types of addresses are not assigned any special meaning by this implementation,
	/// other than what the relevant standards prescribe. This means that an address like `::ffff:127.0.0.1`,
	/// while representing an IPv4 loopback address, is not itself an IPv6 loopback address; only `::1` is.
	/// To handle these so called "IPv4-in-IPv6" addresses, they have to first be converted to their canonical IPv4 address.

[dtolnay]

@rust-lang/libs-api:
@rfcbot fcp merge

[rfcbot]

Team member @dtolnay has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @m-ou-se

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[tgross35]

Is is_unicast_global worth including as part of the unicast family?

These methods, along with similar unstabilized ones, have unfortunately had a pretty rough time getting finalized. I added unresolved questions to the tracking issue at #27709 to list some of these concerns. Most relevant here:

• Make sure IPv6 Unicast Interface #85604 has been addressed (@CDirkx)
• Check if we want the enum idea from Stabilize the "IP" feature #76098 (comment). Imo we should consider this for consistency with Ipv6MulticastScope (or change that since it also unstable, but I think the enum is nicer)

There is a tool designed to check our IP methods against those from other languages, could you try to run it to see where we stand? https://github.com/rust-lang/libs-team/tree/main/tools/ipcheck?

(I can't find the original PR for is_unqiue_local)

It predates rust 1 :) #22015 also typo unqiue/unique if you were searching for that exact string.

[umgefahren]

I ran the ipcheck tool, some of my changes I applied can be seen in my PR: rust-lang/libs-team#454

Complete output of a run

Found Rust implementation.
Found .NET implementation.
Found Go implementation.
Found Java implementation.

addr	.NET	Go	Java
0.0.0.0	✔️	✔️	✔️
0.1.2.3	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
1.1.1.1	✔️	✔️	✔️
127.0.0.1	✔️	✔️	✔️
255.255.255.255	✔️	✔️	✔️
10.0.0.1	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
16.89.10.65	✔️	✔️	✔️
45.22.13.197	✔️	✔️	✔️
100.64.0.0	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
100.128.0.0	✔️	✔️	✔️
169.254.0.0	✔️	✔️	✔️
172.16.10.10	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
192.0.0.0	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
192.0.0.7	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
192.0.0.8	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
192.0.0.9	✔️	✔️	✔️
192.0.0.10	✔️	✔️	✔️
192.0.0.169	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
192.0.0.170	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
192.0.0.171	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
192.0.0.172	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
192.0.0.255	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
192.0.2.2	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
192.31.196.2	✔️	✔️	✔️
192.52.193.2	✔️	✔️	✔️
192.88.99.2	✔️	✔️	✔️
192.168.0.2	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
192.175.48.2	✔️	✔️	✔️
198.18.0.0	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
198.51.100.2	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
203.0.113.6	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
240.0.0.0	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
255.255.255.254	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::ffff:0.0.0.0	✔️	❌ { is_unspecified : false (Rust) ≠ true (Go) }	✔️
::ffff:0.1.2.3	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::ffff:1.1.1.1	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::ffff:127.0.0.1	❌ { is_loopback : false (Rust) ≠ true (.NET) }	❌ { is_loopback : false (Rust) ≠ true (Go) }	❌ { is_loopback : false (Rust) ≠ true (Java) }
::ffff:255.255.255.255	✔️	✔️	✔️
::ffff:10.0.0.1	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::ffff:16.89.10.65	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::ffff:45.22.13.197	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::ffff:100.64.0.0	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::ffff:100.128.0.0	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::ffff:169.254.0.0	✔️	❌ { is_unicast_link_local : false (Rust) ≠ true (Go) }	✔️
::ffff:172.16.10.10	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::ffff:192.0.0.0	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::ffff:192.0.0.7	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::ffff:192.0.0.8	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::ffff:192.0.0.9	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::ffff:192.0.0.10	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::ffff:192.0.0.169	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::ffff:192.0.0.170	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::ffff:192.0.0.171	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::ffff:192.0.0.172	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::ffff:192.0.0.255	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::ffff:192.0.2.2	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::ffff:192.31.196.2	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::ffff:192.52.193.2	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::ffff:192.88.99.2	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::ffff:192.168.0.2	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::ffff:192.175.48.2	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::ffff:198.18.0.0	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::ffff:198.51.100.2	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::ffff:203.0.113.6	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::ffff:240.0.0.0	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::ffff:255.255.255.254	✔️	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
::1	✔️	✔️	✔️
::	✔️	✔️	✔️
64:ff9b::	❌ { to_ipv4 : null (Rust) ≠ "0.0.0.0" (.NET) }	✔️	✔️
64:ff9b:1::	❌ { to_ipv4 : null (Rust) ≠ "0.0.0.0" (.NET) }	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
100::	❌ { to_ipv4 : null (Rust) ≠ "0.0.0.0" (.NET) }	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
2001::	❌ { to_ipv4 : null (Rust) ≠ "0.0.0.0" (.NET) }	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
2001:1::1	❌ { to_ipv4 : null (Rust) ≠ "0.0.0.1" (.NET) }	✔️	✔️
2001:1::2	❌ { to_ipv4 : null (Rust) ≠ "0.0.0.2" (.NET) }	✔️	✔️
2001:2::	❌ { to_ipv4 : null (Rust) ≠ "0.0.0.0" (.NET) }	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
2001:0002:6c::430	❌ { to_ipv4 : null (Rust) ≠ "0.0.4.48" (.NET) }	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
2001:3::	❌ { to_ipv4 : null (Rust) ≠ "0.0.0.0" (.NET) }	✔️	✔️
2001:4:112::	❌ { to_ipv4 : null (Rust) ≠ "0.0.0.0" (.NET) }	✔️	✔️
2001:10::	❌ { to_ipv4 : null (Rust) ≠ "0.0.0.0" (.NET) }	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
2001:10:240:ab::a	❌ { to_ipv4 : null (Rust) ≠ "0.0.0.10" (.NET) }	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
2001:20::	❌ { to_ipv4 : null (Rust) ≠ "0.0.0.0" (.NET) }	✔️	✔️
2001:30::	❌ { to_ipv4 : null (Rust) ≠ "0.0.0.0" (.NET) }	✔️	✔️
2001:db8:8:4::2	❌ { to_ipv4 : null (Rust) ≠ "0.0.0.2" (.NET) }	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
2002::	❌ { to_ipv4 : null (Rust) ≠ "0.0.0.0" (.NET) }	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
2002:cb0a:3cdd:1::1	❌ { to_ipv4 : null (Rust) ≠ "0.0.0.1" (.NET) }	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
2620:4f:8000::	❌ { to_ipv4 : null (Rust) ≠ "0.0.0.0" (.NET) }	✔️	✔️
fdf8:f53b:82e4::53	❌ { to_ipv4 : null (Rust) ≠ "0.0.0.83" (.NET) }	❌ { is_global : false (Rust) ≠ true (Go) }	✔️
fe80::200:5aee:feaa:20a2	❌ { to_ipv4 : null (Rust) ≠ "254.170.32.162" (.NET) }	✔️	✔️
ff01:0:0:0:0:0:0:2	❌ { to_ipv4 : null (Rust) ≠ "0.0.0.2" (.NET) }	❌ { is_global : true (Rust) ≠ false (Go) }	✔️

Operations with only a Rust implementation:

• is_benchmarking
• is_documentation
• is_reserved
• is_shared
• is_unique_local
• mc_scope_admin_local
• mc_scope_realm_local
• mc_scope_reserved
• mc_scope_unassigned

Summary

As far as I can see the difference in output in is_loopback and is_unicast_link_local is a matter of opinion. They boil down to the differentiation of how IPv4 to IPv6 addresses are handled, as @dtolnay already pointed out: #129238 (comment)

However since Rust went a different way anyway in handling these cases, I would recon that we can assume Rust is compatible with other languages, however there exists a pitfall.

[umgefahren]

• Check if we want the enum idea from Stabilize the "IP" feature #76098 (comment). Imo we should consider this for consistency with Ipv6MulticastScope (or change that since it also unstable, but I think the enum is nicer)

I'm open to discussion here. If you want to see how it looks, I could include it in this.

[thvdveld]

I agree with @tgross35 that adding this would make it more consistent with Ipv6MulticastScope. I'd be in favour of adding this.

[tgross35]

@thvdveld do you have an idea how this should look? If so, that could be submitted as an ACP (or just put up a PR changing it)

[thvdveld]

What I get from https://www.rfc-editor.org/rfc/rfc4291#section-2.5: there are only two scope types for unicast addresses: global unicast and link-local unicast. However, I think we could also add UniqueLocal, Unspecified, Benchmarking, Documentation, Loopback, but I'm not sure if those are really a scope.

[bors]

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

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[tgross35]

@joshtriplett (or others who checked for FCP) could you ack that the Ipv6UnicastScope enum idea mentioned above was considered & rejected rather than overlooked? Just making sure :)

[dtolnay]

Thank you!

I think stabilizing these as-is is good. I am open to a separate Ipv6UnicastScope API in addition if someone can express use cases for it beyond just replacing if ip.is_unicast_link_local() with if let Some(Ipv6UnicastScope::LinkLocal) = ip.unicast_scope().

For me the API of the IP types is governed by exposing the behaviors that people want in real-world usage, that are well-specified, and using naming that aligns with term-of-art in a specification where possible. This is a different set of factors than the API for something like Result, where the possible behaviors people want is boundless, and the naming space is cramped, and the design needs to be driven by using a small number of naming schemes/fragments to describe orthogonal and composable behaviors.

[dtolnay]

@bors r+

[dtolnay]

@bors ping

[dtolnay]

@bors ping

[bors]

😪 I'm awake I'm awake

[dtolnay]

@bors r+

[bors]

📌 Commit 9cca296 has been approved by dtolnay

It is now in the queue for this repository.

[bors]

⌛ Testing commit 9cca296 with merge 6b5b526...

[compiler-errors]

Yield to rollup

@bors retry

[bors]

⌛ Testing commit 9cca296 with merge 2cf7908...

[bors]

☀️ Test successful - checks-actions
Approved by: dtolnay
Pushing 2cf7908 to master...

[rust-timer]

Finished benchmarking commit (2cf7908): comparison URL.

Overall result: no relevant changes - no action needed

@rustbot label: -perf-regression

Instruction count

This benchmark run did not return any relevant results for this metric.

Max RSS (memory usage)

Results (primary -1.3%, secondary 3.2%)

This is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.

	mean	range	count
Regressions ❌ (primary)	-	-	0
Regressions ❌ (secondary)	3.2%	[3.1%, 3.2%]	2
Improvements ✅ (primary)	-1.3%	[-1.3%, -1.3%]	1
Improvements ✅ (secondary)	-	-	0
All ❌✅ (primary)	-1.3%	[-1.3%, -1.3%]	1

Cycles

Results (primary -2.2%)

This is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.

	mean	range	count
Regressions ❌ (primary)	-	-	0
Regressions ❌ (secondary)	-	-	0
Improvements ✅ (primary)	-2.2%	[-2.2%, -2.2%]	1
Improvements ✅ (secondary)	-	-	0
All ❌✅ (primary)	-2.2%	[-2.2%, -2.2%]	1

Binary size

This benchmark run did not return any relevant results for this metric.

Bootstrap: 796.222s -> 796.948s (0.09%)
Artifact size: 336.06 MiB -> 335.99 MiB (-0.02%)