ACP(core::net): add Ipv[4|6]Address::from_octets and Ipv6Address::from_segments · Issue #447 · rust-lang/libs-team (original) (raw)

Proposal: Add Ipv[4|6]Address::from_octets and Ipv6Address::from_segments

Problem statement

It is common to convert &[u8] to an Ipv[4|6]Addr. This can currently be achieved using:

which requires us to write:

Ipv4Addr::from(<[u8;4]>::try_from(x).unwrap())

or

Ipv6Addr::from(<[u8;16]>::try_from(x).unwrap())

This is not convenient as the type needs to be implicitly written.

Motivating examples or use cases

Packets are usually just &[u8], which a TCP/IP stack needs to parse. Indexing the fields return either a u8 or a &[u8] when the field is one octet or multiple octets, respectively. Creating an IP address therefore requires us to parse a &[u8] into an Ipv4Addr or Ipv6Addr.

To achieve this in C#, the public IPAddress (byte[] address) can be used. When the address contains 4 elements, an IPv4 address is constructed. For other cases, an IPv6 address is constructed.

In go, an address can also be constructed by a byte array, without specifying the length of the array.

addr := net.IP([]byte{192, 168, 1, 1})

Python also allows creating an address by passing a bytes object.

smoltcp is a TCP/IP stack, which contains custom Ipv[4|6]Address types, instead of using core:🥅:Ipv[4|6]Addr. The network stack parses IPv6 address like this:

/// Return the source address field. #[inline] pub fn src_addr(&self) -> Address { let data = self.buffer.as_ref(); Address::from_bytes(&data[field::SRC_ADDR]) }

This ACP seeks to add functions which allow creating addresses from a &[u8], where the compiler can infer the type when calling try_into().

Solution sketch

By adding the following functions:

pub const fn from_octets(octets: [u8; 4]) -> Ipv4Addr { Ipv4Addr { octets } }

pub const fn from_octets(octets: [u8; 16]) -> Ipv6Addr { Ipv6Addr { octets } }

pub const fn from_segments(segments: [u16; 8]) -> Ipv6Addr { let [a, b, c, d, e, f, g, h] = segments; Ipv6Addr::new(a, b, c, d, e, f, g, h) }

the compiler can infer the type for try_into(), which was previously not possible with the From implementations

let octets: &[u8] = &[127, 0, 0, 1][..]; Ipv4Address::from_octets(<[u8; 4]>::try_into(octets).unwrap());

can now be written as

let octets: &[u8] = &[127, 0, 0, 1][..]; Ipv4Address::from_octets(octets.try_into().unwrap());

These functions are consistent with the Ipv4Addr::octets(&self) -> [u8; 4], Ipv6Addr::octets(&self) -> [u8; 16] and Ipv6Addr::segments(&self) -> [u16; 8] functions.

Another way of easily constructing an address from a &[u8], would be by implementing:

impl TryFrom<&[u8]> for Ipv4Addr impl TryFrom<&[u8]> for Ipv6Addr

This would make it possible to construct an address as:

Ipv4Addr::try_from(some_slice).unwrap(); Ipv6Addr::try_from(some_slice).unwrap();

Alternatives

Instead of using try_into to convert &[u8] to [u8; 4] or [u8; 16], from_octets could just take a &[u8], and panic when the length is not 4 or 16 for Ipv4Addr and Ipv6Addr respectively.

rust-lang/rust#130629 already implements this ACP.

C# documentation: https://learn.microsoft.com/en-us/dotnet/api/system.net.ipaddress.-ctor?view=net-8.0#system-net-ipaddress-ctor(system-byte())

go documentation: https://pkg.go.dev/net#IP

Python documentation: https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv4Address

What happens now?

This issue contains an API change proposal (or ACP) and is part of the libs-api team feature lifecycle. Once this issue is filed, the libs-api team will review open proposals as capability becomes available. Current response times do not have a clear estimate, but may be up to several months.

Possible responses

The libs team may respond in various different ways. First, the team will consider the problem (this doesn't require any concrete solution or alternatives to have been proposed):

Second, if there's a concrete solution: