chore: import upstream snapshot with attribution

Sources/ContainerResource/Network/Attachment.swift

@@ -0,0 +1,109 @@
+//===----------------------------------------------------------------------===//
+// Copyright © 2026 Apple Inc. and the container 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.
+//===----------------------------------------------------------------------===//
+
+import ContainerizationExtras
+
+/// A snapshot of a network interface for a sandbox.
+public struct Attachment: Codable, Sendable {
+    /// The network ID associated with the attachment.
+    public let network: String
+    /// The hostname associated with the attachment.
+    public let hostname: String
+    /// The CIDR address describing the interface IPv4 address, with the prefix length of the subnet.
+    public let ipv4Address: CIDRv4
+    /// The IPv4 gateway address.
+    public let ipv4Gateway: IPv4Address
+    /// The CIDR address describing the interface IPv6 address, with the prefix length of the subnet.
+    /// The address is nil if the IPv6 subnet could not be determined at network creation time.
+    public let ipv6Address: CIDRv6?
+    /// The MAC address associated with the attachment (optional).
+    public let macAddress: MACAddress?
+    /// The MTU for the network interface.
+    public let mtu: UInt32?
+    /// The network plugin variant, used by the runtime to select an interface strategy.
+    public let variant: String?
+
+    public init(
+        network: String,
+        hostname: String,
+        ipv4Address: CIDRv4,
+        ipv4Gateway: IPv4Address,
+        ipv6Address: CIDRv6?,
+        macAddress: MACAddress?,
+        mtu: UInt32? = nil,
+        variant: String? = nil
+    ) {
+        self.network = network
+        self.hostname = hostname
+        self.ipv4Address = ipv4Address
+        self.ipv4Gateway = ipv4Gateway
+        self.ipv6Address = ipv6Address
+        self.macAddress = macAddress
+        self.mtu = mtu
+        self.variant = variant
+    }
+
+    enum CodingKeys: String, CodingKey {
+        case network
+        case hostname
+        case ipv4Address
+        case ipv4Gateway
+        case ipv6Address
+        case macAddress
+        case mtu
+        case variant
+        // TODO: retain for deserialization compatibility for now, remove later
+        case address
+        case gateway
+    }
+
+    /// Create a configuration from the supplied Decoder, initializing missing
+    /// values where possible to reasonable defaults.
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+
+        network = try container.decode(String.self, forKey: .network)
+        hostname = try container.decode(String.self, forKey: .hostname)
+        if let address = try? container.decode(CIDRv4.self, forKey: .ipv4Address) {
+            ipv4Address = address
+        } else {
+            ipv4Address = try container.decode(CIDRv4.self, forKey: .address)
+        }
+        if let gateway = try? container.decode(IPv4Address.self, forKey: .ipv4Gateway) {
+            ipv4Gateway = gateway
+        } else {
+            ipv4Gateway = try container.decode(IPv4Address.self, forKey: .gateway)
+        }
+        ipv6Address = try container.decodeIfPresent(CIDRv6.self, forKey: .ipv6Address)
+        macAddress = try container.decodeIfPresent(MACAddress.self, forKey: .macAddress)
+        mtu = try container.decodeIfPresent(UInt32.self, forKey: .mtu)
+        variant = try container.decodeIfPresent(String.self, forKey: .variant)
+    }
+
+    /// Encode the configuration to the supplied Encoder.
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+
+        try container.encode(network, forKey: .network)
+        try container.encode(hostname, forKey: .hostname)
+        try container.encode(ipv4Address, forKey: .ipv4Address)
+        try container.encode(ipv4Gateway, forKey: .ipv4Gateway)
+        try container.encodeIfPresent(ipv6Address, forKey: .ipv6Address)
+        try container.encodeIfPresent(macAddress, forKey: .macAddress)
+        try container.encodeIfPresent(mtu, forKey: .mtu)
+        try container.encodeIfPresent(variant, forKey: .variant)
+    }
+}

Sources/ContainerResource/Network/AttachmentConfiguration.swift

@@ -0,0 +1,49 @@
+//===----------------------------------------------------------------------===//
+// Copyright © 2026 Apple Inc. and the container 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.
+//===----------------------------------------------------------------------===//
+
+import ContainerizationExtras
+
+/// Configuration information for attaching a container network interface to a network.
+public struct AttachmentConfiguration: Codable, Sendable {
+    /// The network ID associated with the attachment.
+    public let network: String
+
+    /// The option information for the attachment
+    public let options: AttachmentOptions
+
+    public init(network: String, options: AttachmentOptions) {
+        self.network = network
+        self.options = options
+    }
+}
+
+// Option information for a network attachment.
+public struct AttachmentOptions: Codable, Sendable {
+    /// The hostname associated with the attachment.
+    public let hostname: String
+
+    /// The MAC address associated with the attachment (optional).
+    public let macAddress: MACAddress?
+
+    /// The MTU for the network interface.
+    public let mtu: UInt32?
+
+    public init(hostname: String, macAddress: MACAddress? = nil, mtu: UInt32? = nil) {
+        self.hostname = hostname
+        self.macAddress = macAddress
+        self.mtu = mtu
+    }
+}

Sources/ContainerResource/Network/NetworkConfiguration.swift

@@ -0,0 +1,151 @@
+//===----------------------------------------------------------------------===//
+// Copyright © 2026 Apple Inc. and the container 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.
+//===----------------------------------------------------------------------===//
+
+import ContainerizationError
+import ContainerizationExtras
+import Foundation
+
+/// Configuration parameters for network creation.
+public struct NetworkConfiguration: Codable, Sendable, Identifiable {
+    /// The name of the network.
+    public let name: String
+
+    /// The unique identifier for the network. Identical to ``name``.
+    public var id: String { name }
+
+    /// The network type
+    public let mode: NetworkMode
+
+    /// When the network was created.
+    public let creationDate: Date
+
+    /// The preferred CIDR address for the IPv4 subnet, if specified
+    public let ipv4Subnet: CIDRv4?
+
+    /// The preferred CIDR address for the IPv6 subnet, if specified
+    public let ipv6Subnet: CIDRv6?
+
+    /// Key-value labels for the network.
+    /// Resource labels should not be mutated, except while building a network configurations.
+    public let labels: ResourceLabels
+
+    /// The network plugin that manages this network.
+    public let plugin: String
+
+    /// Plugin-specific options for this network.
+    public let options: [String: String]
+
+    /// Creates a network configuration
+    public init(
+        name: String,
+        mode: NetworkMode,
+        ipv4Subnet: CIDRv4? = nil,
+        ipv6Subnet: CIDRv6? = nil,
+        labels: ResourceLabels = .init(),
+        plugin: String,
+        options: [String: String] = [:]
+    ) throws {
+        self.name = name
+        self.creationDate = Date()
+        self.mode = mode
+        self.ipv4Subnet = ipv4Subnet
+        self.ipv6Subnet = ipv6Subnet
+        self.labels = labels
+        self.plugin = plugin
+        self.options = options
+        try validate()
+    }
+
+    enum CodingKeys: String, CodingKey {
+        case name
+        // Deprecated: As of 1.0.0. Use ``name`` instead of ``id``.
+        // Note: Will be removed in a later release.
+        case id
+        case creationDate
+        case mode
+        case ipv4Subnet
+        case ipv6Subnet
+        case labels
+        case plugin
+        case options
+        // TODO: retain for deserialization compatibility, remove in next major version
+        case pluginInfo
+        case subnet
+    }
+
+    /// Create a configuration from the supplied Decoder, initializing missing
+    /// values where possible to reasonable defaults.
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+
+        name =
+            try container.decodeIfPresent(String.self, forKey: .name)
+            ?? container.decode(String.self, forKey: .id)
+        creationDate = try container.decodeIfPresent(Date.self, forKey: .creationDate) ?? Date(timeIntervalSince1970: 0)
+        mode = try container.decode(NetworkMode.self, forKey: .mode)
+        let subnetText =
+            try container.decodeIfPresent(String.self, forKey: .ipv4Subnet)
+            ?? container.decodeIfPresent(String.self, forKey: .subnet)
+        ipv4Subnet = try subnetText.map { try CIDRv4($0) }
+        ipv6Subnet = try container.decodeIfPresent(String.self, forKey: .ipv6Subnet)
+            .map { try CIDRv6($0) }
+        let decodedLabels = try container.decodeIfPresent([String: String].self, forKey: .labels) ?? [:]
+        labels = try .init(decodedLabels)
+
+        if let plugin = try container.decodeIfPresent(String.self, forKey: .plugin) {
+            self.plugin = plugin
+            self.options = try container.decodeIfPresent([String: String].self, forKey: .options) ?? [:]
+        } else if let legacy = try container.decodeIfPresent(_LegacyPluginInfo.self, forKey: .pluginInfo) {
+            // Deprecated: As of 1.0.0. Use ``plugin`` and ``options`` instead.
+            // Note: Will be removed in a later release.
+            self.plugin = legacy.plugin
+            var opts: [String: String] = [:]
+            if let variant = legacy.variant { opts["variant"] = variant }
+            self.options = opts
+        } else {
+            self.plugin = "container-network-vmnet"
+            self.options = [:]
+        }
+
+        try validate()
+    }
+
+    /// Encode the configuration to the supplied Encoder.
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+
+        try container.encode(name, forKey: .name)
+        try container.encode(creationDate, forKey: .creationDate)
+        try container.encode(mode, forKey: .mode)
+        try container.encodeIfPresent(ipv4Subnet, forKey: .ipv4Subnet)
+        try container.encodeIfPresent(ipv6Subnet, forKey: .ipv6Subnet)
+        try container.encode(labels, forKey: .labels)
+        try container.encode(plugin, forKey: .plugin)
+        try container.encode(options, forKey: .options)
+    }
+
+    private func validate() throws {
+        guard NetworkResource.nameValid(name) else {
+            throw ContainerizationError(.invalidArgument, message: "invalid network name: \(name)")
+        }
+    }
+}
+
+/// Decode helper for stored configurations that used the old `pluginInfo` key.
+private struct _LegacyPluginInfo: Codable {
+    let plugin: String
+    let variant: String?
+}

Sources/ContainerResource/Network/NetworkMode.swift

@@ -0,0 +1,41 @@
+//===----------------------------------------------------------------------===//
+// Copyright © 2026 Apple Inc. and the container 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.
+//===----------------------------------------------------------------------===//
+
+/// Networking mode that applies to client containers.
+public enum NetworkMode: String, Codable, Sendable {
+    /// NAT networking mode.
+    /// Containers do not have routable IPs, and the host performs network
+    /// address translation to allow containers to reach external services.
+    case nat = "nat"
+
+    /// Host only networking mode
+    /// Containers can talk with each other in the same subnet only.
+    case hostOnly = "hostOnly"
+}
+
+extension NetworkMode {
+    public init() {
+        self = .nat
+    }
+
+    public init?(_ value: String) {
+        switch value.lowercased() {
+        case "nat": self = .nat
+        case "hostOnly": self = .hostOnly
+        default: return nil
+        }
+    }
+}

Sources/ContainerResource/Network/NetworkResource.swift

@@ -0,0 +1,96 @@
+//===----------------------------------------------------------------------===//
+// Copyright © 2026 Apple Inc. and the container 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.
+//===----------------------------------------------------------------------===//
+
+import ContainerizationExtras
+import Foundation
+
+/// A network resource, representing a configured virtual network and its runtime status.
+///
+/// `NetworkResource` conforms to `ManagedResource` and separates the network's
+/// intrinsic configuration from its runtime status — following the same config/status
+/// split used by Kubernetes and Docker. `configuration` is persisted; `status` reflects
+/// what the network plugin reports at runtime.
+///
+/// JSON encoding produces three top-level keys: `id`, `configuration` (the persistent
+/// config), and `status` (runtime address properties assigned by the network plugin).
+public struct NetworkResource: ManagedResource {
+    /// The network's configuration — its persistent, intrinsic properties.
+    public let configuration: NetworkConfiguration
+
+    /// The network's runtime status — the addresses assigned by the network plugin.
+    public let status: NetworkStatus
+
+    // MARK: ManagedResource
+
+    /// The unique identifier for this network. Identical to ``configuration/name``.
+    public var id: String { configuration.name }
+
+    /// The user-assigned name for this network. For networks, name and ID are the same.
+    public var name: String { configuration.name }
+
+    /// The time at which this network was created.
+    public var creationDate: Date { configuration.creationDate }
+
+    /// Key-value labels for this network.
+    public var labels: ResourceLabels { configuration.labels }
+
+    /// Returns `true` for a system-managed network that cannot be deleted by the user.
+    public var isBuiltin: Bool { labels.isBuiltin }
+
+    /// Returns `true` if `name` is a syntactically valid network identifier.
+    ///
+    /// Valid network names are lowercase alphanumeric strings of up to 63
+    /// characters, allowing dots, hyphens, and underscores in interior positions.
+    public static func nameValid(_ name: String) -> Bool {
+        let pattern = #"^[a-z0-9](?:[a-z0-9._-]{0,61}[a-z0-9])?$"#
+        return name.range(of: pattern, options: .regularExpression) != nil
+    }
+
+    // MARK: Initialization
+
+    /// Creates a network resource.
+    ///
+    /// - Parameters:
+    ///   - configuration: The network's intrinsic configuration.
+    ///   - status: The runtime status reported by the network plugin.
+    public init(configuration: NetworkConfiguration, status: NetworkStatus) {
+        self.configuration = configuration
+        self.status = status
+    }
+}
+
+// MARK: - Codable
+
+extension NetworkResource {
+    enum CodingKeys: String, CodingKey {
+        case id
+        case configuration
+        case status
+    }
+
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        try container.encode(id, forKey: .id)
+        try container.encode(configuration, forKey: .configuration)
+        try container.encode(status, forKey: .status)
+    }
+
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        configuration = try container.decode(NetworkConfiguration.self, forKey: .configuration)
+        status = try container.decode(NetworkStatus.self, forKey: .status)
+    }
+}

Sources/ContainerResource/Network/NetworkStatus.swift

@@ -0,0 +1,40 @@
+//===----------------------------------------------------------------------===//
+// Copyright © 2026 Apple Inc. and the container 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.
+//===----------------------------------------------------------------------===//
+
+import ContainerizationExtras
+
+/// The runtime status of a network — the addresses assigned once the network
+/// plugin is active. Only present after the network has started.
+public struct NetworkStatus: Codable, Sendable {
+    /// The IPv4 subnet assigned to the network.
+    public let ipv4Subnet: CIDRv4
+
+    /// The IPv4 gateway address.
+    public let ipv4Gateway: IPv4Address
+
+    /// The IPv6 subnet assigned to the network, if IPv6 is enabled.
+    public let ipv6Subnet: CIDRv6?
+
+    public init(
+        ipv4Subnet: CIDRv4,
+        ipv4Gateway: IPv4Address,
+        ipv6Subnet: CIDRv6?
+    ) {
+        self.ipv4Subnet = ipv4Subnet
+        self.ipv4Gateway = ipv4Gateway
+        self.ipv6Subnet = ipv6Subnet
+    }
+}