Add CIDR Block logic to System.Net

[scottgorlick]

leveraging the base IPAddress and IPAddressParser, I would like to introduce CIDR block data structures and extension methods for behaviors. I have implemented this logic in .NET and want to port it to dotnet core. I feel the timing of this addition fits with the upcoming 5.0 release milestone.

the structures I propose are:
IPNumeric / IPNumericV4 / IPNumericV6 - data structures. These structures make the logic in CidrBlock much simpler. This is the "arithmetic" and CidrBlock is the Geometry.

CidrBlock - IP Address logic useful in handling CIDR notation concepts

CidrBlockExtensions - Set logic for CidrBlocks, such as IsAdjacent, Contains, Overlaps

Tagging subscribers to this area: @dotnet/ncl
Notify danmosemsft if you want to be subscribed.

[scalablecory]

Hi @scottgorlick, can you please propose the full API surface here so we can discuss? It would also be helpful if you can include concrete use cases and examples.

[scottgorlick]

was typing this up as you commented @scalablecory...

API Design:
IPNumeric Interface:

public interface IpNumeric : IComparable, IComparable<IpNumeric>
{
    static int DefaultMaskLength { get; }

    byte[] GetBytes();

    int IComparable.CompareTo(object? obj);
    int IComparable<IpNumeric>.CompareTo(IpNumeric other);

    IpNumeric Subtract(IpNumeric rhs);
    IpNumeric Subtract(Int32 rhs);
    IpNumeric Subtract(UInt32 rhs);

    IpNumeric Add(IpNumeric rhs);
    IpNumeric Add(Int32 rhs);
    IpNumeric Add(UInt32 rhs);

    static IpNumeric FromAddress(IPAddress address);

    bool Equals(object? other);       
}

CidrBlock Class (would be implemented without inheritence from IPAddress class (since IPAddressParser is now a discrete class)

public class CidrBlock : IPAddress, IComparable, IComparable<CidrBlock>, IComparable<IPAddress>, ISerializable
{
    public int MaskLength { get; private set; }
    public bool IsNetworkAddress { get; }
    public bool IsBroadcastAddress { get; } 
    public bool IsHostAddress { get; }
   
    /// should move to Extensions
    public bool IsRfc1918Block { get; }

    public CidrBlock BroadcastAddress { get; }
    public CidrBlock NetworkAddress { get; }
    
    public string ToString(bool includeMaskLength);

    public override string ToString();

    /// will move to a Parser class
    public new static CidrBlock Parse(string ipAddress);
    public static IPAddress Parse(string ipAddress, int mask);   
    public static bool TryParse(string? ipAddress, out CidrBlock? address);           

    /// IComparable
    public int CompareTo(object? obj);
    public int CompareTo(CidrBlock? other);
    public int CompareTo(IPAddress? address);
    
    /// implemented operators   
    public static CidrBlock operator +(Int32 lhs, CidrBlock? rhs);
    public static CidrBlock operator +(UInt32 lhs, CidrBlock? rhs);
    public static CidrBlock operator +(CidrBlock? lhs, Int32 rhs);
    public static CidrBlock operator +(CidrBlock? lhs, UInt32 rhs);
    public static CidrBlock operator -(Int32 lhs, CidrBlock? rhs);
    public static CidrBlock operator -(UInt32 lhs, CidrBlock? rhs);
    public static CidrBlock operator -(CidrBlock? lhs, Int32 rhs);
    public static CidrBlock operator -(CidrBlock? lhs, UInt32 rhs);
    public static CidrBlock operator ++(CidrBlock? lhs);
    public static CidrBlock operator --(CidrBlock? lhs);
    public static bool operator >(CidrBlock? lhs, CidrBlock? rhs);
    public static bool operator >(CidrBlock? lhs, IPAddress? rhs);
    public static bool operator >(IPAddress? lhs, CidrBlock? rhs);
    public static bool operator <(CidrBlock? lhs, CidrBlock? rhs);    
    public static bool operator <(CidrBlock? lhs, IPAddress? rhs);
    public static bool operator <(IPAddress? lhs, CidrBlock? rhs);
    public static bool operator ==(CidrBlock? lhs, CidrBlock? rhs);
    public static bool operator ==(CidrBlock? lhs, IPAddress? rhs);
    public static bool operator ==(IPAddress? lhs, CidrBlock? rhs);
    public static bool operator !=(CidrBlock? lhs, CidrBlock? rhs);
    public static bool operator !=(CidrBlock? lhs, IPAddress? rhs);
    public static bool operator !=(IPAddress? lhs, CidrBlock? rhs);
    public static bool operator <=(CidrBlock? lhs, CidrBlock? rhs);
    public static bool operator <=(CidrBlock? lhs, IPAddress? rhs);
    public static bool operator <=(IPAddress? lhs, CidrBlock? rhs);
    public static bool operator >=(CidrBlock? lhs, CidrBlock? rhs);
    public static bool operator >=(CidrBlock? lhs, IPAddress? rhs);
    public static bool operator >=(IPAddress? lhs, CidrBlock? rhs);
}

CidrBlockExtensions

Contains logic related to comparisons for block aggregation and other error detections wrt IP Address provisioning... Overlaps, for instance, is a useful tool when designing IP networks

public static class CidrBlockExtensions
{
    /// <summary>
    /// determines if the two <see cref="IPAddress" /> are adjacent to each other
    /// </summary>
    /// <param name="lhs"></param>
    /// <param name="rhs"></param>
    /// <returns><c>true</c> if <paramref name="lhs" /> is numerically one greater or less than <paramref name="rhs">, otherwise, <c>false</c></returns>
    public static bool IsAdjacentTo(this IPAddress? lhs, IPAddress? rhs);

    /// <summary>
    /// determines if the <see cref="IPAddress" /> is adjacent to the <see cref="CidrBlock" />
    /// </summary>
    /// <param name="lhs"></param>
    /// <param name="rhs"></param>
    /// <returns><c>true</c> if <paramref name="lhs" /> is numerically one greater or less than <paramref name="rhs"> Network or Broadcast address, otherwise, <c>false</c></returns>
    public static bool IsAdjacentTo(this IPAddress? lhs, CidrBlock? rhs);
    
    /// <summary>
    /// determines if the <see cref="IPAddress" /> is adjacent to the <see cref="CidrBlock" />
    /// </summary>
    /// <param name="lhs"></param>
    /// <param name="rhs"></param>
    /// <returns><c>true</c> if <paramref name="lhs" /> Broadcast or Network address is numerically one greater or less than <paramref name="rhs">, otherwise, <c>false</c></returns>
    public static bool IsAdjacentTo(this CidrBlock? lhs, IPAddress? rhs);

    /// <summary>
    /// determines if the two <see cref="CidrBlock" /> are adjacent to each other
    /// </summary>
    /// <param name="lhs"></param>
    /// <param name="rhs"></param>
    /// <returns><c>true</c> if <paramref name="lhs" /> Broadcast or Network address is numerically one greater or less than  <paramref name="rhs"> Network or Broadcast address, otherwise, <c>false</c></returns>
    public static bool IsAdjacentTo(this CidrBlock? lhs, CidrBlock? rhs);

    /// <summary>
    /// determines if <paramref name="lhs" /> contains <paramref name="rhs" />
    /// </summary>
    /// <param name="lhs"></param>
    /// <param name="rhs"></param>
    /// <returns><c>true</c> if <paramref name="lhs" /> contains <paramref name="rhs" />, otherwise, <c>false</c></returns>   
    public static bool Contains(this CidrBlock? lhs, IPAddress? rhs);

    /// <summary>
    /// determines if <paramref name="lhs" /> contains the entire <paramref name="rhs" /> block
    /// </summary>
    /// <remarks>
    /// logic for this function is that the numeric value of the subnet's network address and the subnet's broadcast address AND 
    /// that the tested value has a longer masklength (smaller subnet) than the left hand subnet
    /// </remarks>
    /// <param name="lhs"></param>
    /// <param name="rhs"></param> 
    /// <returns><c>true</c> if <paramref name="lhs" /> fully contains <paramref name="rhs" />, otherwise, <c>false</c></returns>   
    public static bool Contains(this CidrBlock? lhs, CidrBlock? rhs);
    
    /// <summary>
    /// determines if <paramref name="lhs" /> contains any of the <paramref name="rhs" /> block
    /// <summary>
    /// <param name="lhs"></param>
    /// <param name="rhs"></param>
    /// <returns><c>true</c> if the parameters overlap, otherwise, <c>false</c></returns>
    public static bool Overlaps(this CidrBlock? lhs, CidrBlock? rhs);
}

[karelz]

Triage: This looks like fairly rare scenario for network scanners scenario.
Unless we get higher demand, we would recommend to have an independent package outside of .NET repos / Microsoft to deliver these capabilities.
If it proves valuable and highly used over time, we can add the APIs to the platform later on. Thanks!