container/Sources/ContainerizationExtras/CIDRv4.swift

//===----------------------------------------------------------------------===//
// Copyright © 2025-2026 Apple Inc. and the Containerization project authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//   https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//===----------------------------------------------------------------------===//

/// Describes an IPv4 CIDR address block.
@frozen
public struct CIDRv4: CustomStringConvertible, Equatable, Sendable, Hashable {
    /// The IP component of this CIDR address.
    public let address: IPv4Address

    /// The prefix length of this CIDR address.
    public let prefix: Prefix

    /// Create a CIDR address block.
    public init(_ cidr: String) throws {
        let split = cidr.split(separator: "/")
        guard split.count == 2 else {
            throw CIDR.Error.invalidCIDR(cidr: cidr)
        }
        guard let prefixLength = UInt8(split[1]), let prefix = Prefix(length: prefixLength) else {
            throw CIDR.Error.invalidCIDR(cidr: cidr)
        }

        let address = try IPv4Address(String(split[0]))
        try self.init(address, prefix: prefix)
    }

    /// Create a CIDR address from a member IP and a prefix length.
    public init(_ address: IPv4Address, prefix: Prefix) throws {
        guard prefix.length <= 32 else {
            throw CIDR.Error.invalidCIDR(cidr: "\(address)/\(prefix)")
        }
        self.address = address
        self.prefix = prefix
    }

    /// Create the smallest IPv4 CIDR block that includes the lower and upper bounds.
    ///
    /// - Parameters:
    ///   - lower: The lower bound IPv4 address
    ///   - upper: The upper bound IPv4 address
    /// - Returns: The smallest CIDR block containing both addresses
    /// - Throws: If lower > upper
    public init(lower: IPv4Address, upper: IPv4Address) throws {
        guard lower.value <= upper.value else {
            throw CIDR.Error.invalidAddressRange(lower: lower.description, upper: upper.description)
        }

        for length in 1...32 {
            let prefixLength = Prefix(unchecked: UInt8(length))
            let mask = prefixLength.prefixMask32
            if (lower.value & mask) != (upper.value & mask) {
                let prefix = Prefix(unchecked: UInt8(length - 1))
                let networkAddr = IPv4Address(lower.value & prefix.prefixMask32)
                try self.init(networkAddr, prefix: prefix)
                return
            }
        }
        // Same address - /32 block
        let prefix = Prefix(unchecked: 32)
        let networkAddr = IPv4Address(lower.value & prefix.prefixMask32)
        try self.init(networkAddr, prefix: prefix)
    }

    /// The lowest address in this CIDR block
    @inlinable
    public var lower: IPv4Address {
        IPv4Address(address.value & prefix.prefixMask32)
    }

    /// The highest address in this CIDR block (broadcast address).
    @inlinable
    public var upper: IPv4Address {
        IPv4Address(address.value | prefix.suffixMask32)
    }

    /// Return true if the CIDR block contains the specified address.
    ///
    /// Compares network portion of the given IP address.
    @inlinable
    public func contains(_ ip: IPv4Address) -> Bool {
        (address.value & prefix.prefixMask32) == (ip.value & prefix.prefixMask32)
    }

    /// Retrieve the text representation of the CIDR block.
    public var description: String {
        "\(address)/\(prefix)"
    }
}

extension CIDRv4: Codable {
    public init(from decoder: Decoder) throws {
        let container = try decoder.singleValueContainer()
        let string = try container.decode(String.self)
        try self.init(string)
    }

    public func encode(to encoder: Encoder) throws {
        var container = encoder.singleValueContainer()
        try container.encode(description)
    }
}

extension CIDRv4 {
    /// The gateway address of the network. Conventionally the first usable
    /// address in the subnet (`lower + 1`).
    public var gateway: IPv4Address {
        IPv4Address(self.lower.value + 1)
    }
}