chore: import upstream snapshot with attribution

2026-07-13 12:25:30 +08:00
commit 680845cb1c
445 changed files with 103779 additions and 0 deletions
@@ -0,0 +1,122 @@
+//===----------------------------------------------------------------------===//
+// 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)
+    }
+}