[API Proposal]: Add a type to represent IP networks based on CIDR notation

[geeknoid]

Background and motivation

We've been using a custom IPAddressRange in our project, but this seems like a general-purpose concern. Looking across internal code bases at Microsoft, we've found dozens of similar implementations of this type, reinforcing the notion that this is general-purpose and should be in the framework.

API Proposal

Edit by @antonfirsov: Added implementations for ISpanFormattable and IParsable<IPSubnet>, harmonized naming of method arguments to match current BCL standards.

namespace System.Net;

// Alternative name ideas: IPSubnet, IPAddressSpace
public readonly struct IPNetwork : IEquatable<IPSubnet>, ISpanFormattable, ISpanParsable<IPSubnet>
{
    public IPAddress BaseAddress { get; }
    public byte MaskLength { get; }

    public IPNetwork(IPAddress baseAddress, byte maskLength);

    public bool Contains(IPAddress address);

    // ISpanParsable
    public static IPNetwork Parse(string s, IFormatProvider? provider = null);
    public static bool TryParse(string s, IFormatProvider? provider, out IPNetwork result);
    public static IPNetwork Parse(ReadOnlySpan<char> s, IFormatProvider? provider = null);
    public static bool TryParse(ReadOnlySpan<char> s, IFormatProvider? provider, out IPNetwork result);

    // Parsing - Convenience methods
    public static bool TryParse(string s, out IPNetwork result);
    public static bool TryParse(ReadOnlySpan<char> s, out IPNetwork result);

    // ISpanFormattable
    public string ToString(string? format, IFormatProvider? provider = null);
    public bool TryFormat(Span<char> destination, out int charsWritten, ReadOnlySpan<char> format = default, IFormatProvider? provider = null);

    // Equality
    public bool Equals(IPNetwork value);
    public static bool operator ==(IPNetwork left, IPNetwork right);
    public static bool operator !=(IPNetwork left, IPNetwork right);
}

API Usage

We're using this for parsing and logging, so the parsing and tostring functionality are particularly interesting.

Alternative Designs

This type could potentially implement ISpanFormattable<T> and ISpanParsable<T>, but those interfaces require an IFormatProvider instance which isn't relevant in this context. Still, those interfaces might provide better interop elsewhere in the framework. Note that IPAddress doesn't implement these interfaces either.

Risks

No response

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

Tagging subscribers to this area: @dotnet/ncl
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

We've been using a custom IPAddressRange in our project, but this seems like a general-purpose concern. Looking across internal code bases at Microsoft, we've found dozens of similar implementations of this type, reinforcing the notion that this is general-purpose and should be in the framework.

API Proposal

namespace System.Net;

/// <summary>
/// Represents an IP address range using CIDR notation.
/// </summary>
/// <remarks>The range contains addresses starting with <see cref="BaseAddress"/>,
/// and including every combination of bit values for the rightmost variable part after the subnet mask.
/// I.e. "13.73.248.16/29" will contain 2^3 addresses. 32(IPv4 bits) - 29(subnet mask length) = 3(remaining variable bits).
/// </remarks>
public readonly struct IPAddressRange : IEquatable<IPAddressRange>
{
    /// <summary>
    /// Gets the network prefix in CIDR notation.
    /// </summary>
    /// <remarks><see href="https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation"/>.</remarks>
    public IPAddress BaseAddress { get; }

    /// <summary>
    /// Gets the subnet mask length in bits.
    /// </summary>
    /// <remarks><see href="https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation"/>.</remarks>
    public byte MaskLength { get; }

    /// <summary>
    /// Initializes a new instance of the <see cref="IPAddressRange"/> struct.
    /// </summary>
    /// <param name="baseAddress">Network prefix in CIDR notation.</param>
    /// <param name="maskLength">Subnet mask length in bits.</param>
    public IPAddressRange(IPAddress baseAddress, byte maskLength);

    /// <summary>
    /// Parses string IP range to <see cref="IPAddressRange"/> object.
    /// </summary>
    /// <param name="rangeString">IP range in CIDR notation.</param>
    /// <returns>Parsed IP range.</returns>
    /// <exception cref="FormatException">Thrown if passed value is not in correct format.</exception>
    public static IPAddressRange Parse(string rangeString);

    /// <summary>
    /// Parses string IP range to <see cref="IPAddressRange"/> object.
    /// </summary>
    /// <param name="rangeSpan">IP range in CIDR notation.</param>
    /// <returns>Parsed IP range.</returns>
    /// <exception cref="FormatException">Thrown if passed value is not in correct format.</exception>
    public static IPAddressRange Parse(ReadOnlySpan<char> rangeSpan, IFormatProvider? provider);

    /// <summary>
    /// Parses string IP range to <see cref="IPAddressRange"/> object.
    /// </summary>
    /// <param name="rangeString">IP range in CIDR notation.</param>
    /// <param name="range">Parsed IP range.</param>
    /// <returns><see langword="true"/> if parsing was successful, otherwise <see langword="false"/>.</returns>
    public static bool TryParse(string rangeString, IFormatProvider? provider, out IPAddressRange range);

    /// <summary>
    /// Parses string IP range to <see cref="IPAddressRange"/> object.
    /// </summary>
    /// <param name="rangeSpan">IP range in CIDR notation.</param>
    /// <param name="range">Parsed IP range.</param>
    /// <returns><see langword="true"/> if parsing was successful, otherwise <see langword="false"/>.</returns>
    public static bool TryParse(ReadOnlySpan<char> rangeSpan, out IPAddressRange range);

    /// <summary>
    /// Tests whether a particular address falls within the current range.
    /// </summary>
    /// <param name="ip">The IP address to test.</param>
    /// <returns><see langword="true"> if the given address is covered by the range; otherwise <see langword="false" />.</returns>
    public bool Contains(IPAddress ip);

    /// <summary>
    /// Checks if objects are equal.
    /// </summary>
    /// <param name="obj">Object to check.</param>
    /// <returns>True if equal, false otherwise.</returns>
    public override bool Equals(object? obj);

    /// <summary>
    /// Checks if objects are equal.
    /// </summary>
    /// <param name="other">Object to check.</param>
    /// <returns>True if equal, false otherwise.</returns>
    public bool Equals(IPAddressRange other);

    /// <summary>
    /// Gets hash code.
    /// </summary>
    /// <returns>Hash code.</returns>
    public override int GetHashCode();

    /// <summary>
    /// Produces a CIDR representation of this range.
    /// </summary>
    public override string ToString();

    /// <summary>
    /// Compares two ranges.
    /// </summary>
    /// <param name="left">Left element to compare.</param>
    /// <param name="right">Right element to compare.</param>
    /// <returns><see langword="true" /> when equal, <see langword="false" /> otherwise.</returns>
    public static bool operator ==(IPAddressRange left, IPAddressRange right);

    /// <summary>
    /// Compares two ranges.
    /// </summary>
    /// <param name="left">Left argument of the comparison.</param>
    /// <param name="right">Right argument of the comparison.</param>
    /// <returns><see langword="true" /> when not equal, <see langword="false" /> otherwise.</returns>
    public static bool operator !=(IPAddressRange left, IPAddressRange right);
}

API Usage

We're using this for parsing and logging, so the parsing and tostring functionality are particularly interesting.

Alternative Designs

This type could potentially implement ISpanFormattable<T> and ISpanParsable<T>, but those interfaces require an IFormatProvider instance which isn't relevant in this context. Still, those interfaces might provide better interop elsewhere in the framework. Note that IPAddress doesn't implement these interfaces either.

Risks

No response

Author:	geeknoid
Assignees:	-
Labels:	api-suggestion, area-System.Net, untriaged
Milestone:	-

[teo-tsirpanis]

Should it have a bool TryFormat(Span<char>, out int)?

[NN---]

When I saw IPAddress range, I assumed a range of address not only by a bitmask.
E.g.
AddRange(IPAddress start, IPAddress end)

[svick]

This looks like a duplicate of #64033 and #36428, which were closed as being too niche.

Note that ASP.NET Core does have the IPNetwork class, though it's quite limited.

[sakno]

IPNetwork2 perfectly serves to that purpose.

[geeknoid]

This looks like a duplicate of #64033 and #36428, which were closed as being too niche.

Definitely in the eye of the beholder :-) As I said, we've found dozens of implementations of this within Microsoft's various code bases.

Note that ASP.NET Core does have the IPNetwork class, though it's quite limited.

Missed that one. From a composition perspective, it's a bit too high in the stack for what we'd like I think. But it does show that the concept is a useful one.

[geeknoid]

Should it have a bool TryFormat(Span<char>, out int)?

Definitely could, and it could also implement ISpanFormattable/ISpanParsable. Note that IPAddress could also use these.

[teo-tsirpanis]

And how about we call it IPAddressSubnet? It more closely matches what it is.

[geeknoid]

@mddddb @rymeskar

[mddddb]

And how about we call it IPAddressSubnet? It more closely matches what it is.

IMO in order to make this an actual IP address range maybe we should make this more flexible in terms of the First address and the Last address in the range, i.e. cover the cases of custom address ranges that cannot be covered by CIDR notation (subset of addresses in a subnet).

So we can have both
(IPAddress begin, IPAddress end) and (IPAddress baseAddress, byte maskLength) constructors, and more if needed.
Although I am not sure if we need to have some kind of a property specifying whether the range can be considered valid in CIDR.

[geeknoid]

@mddddb Then the MaskLength property would need to be removed or made optional or something, since a range might not in fact be just a mask thing.