container/Sources/ContainerResource/Image/ImageResource.swift

//===----------------------------------------------------------------------===//
// 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 ContainerizationOCI
import Foundation

/// An image resource, representing an OCI image managed by the system.
///
/// `ImageResource` conforms to `ManagedResource` and wraps the image's
/// ``ImageDescription`` (its reference and index descriptor) alongside the
/// resolved index descriptor and the per-platform variants that make up the
/// image.
public struct ImageResource: ManagedResource {
    /// A single platform-specific variant of an image.
    public struct Variant: Sendable, Codable {
        /// The platform this variant targets.
        public let platform: Platform
        /// The digest of this variant's manifest.
        public let digest: String
        /// The total size of this variant in bytes.
        public let size: Int64
        /// The OCI image config for this variant.
        public let config: ContainerizationOCI.Image

        public init(platform: Platform, digest: String, size: Int64, config: ContainerizationOCI.Image) {
            self.platform = platform
            self.digest = digest
            self.size = size
            self.config = config
        }
    }

    /// Already-resolved OCI content for a single platform manifest, used as
    /// input when building an ``ImageResource``. The variant's total size is
    /// computed from these pieces during initialization.
    public struct ManifestContent {
        /// The manifest descriptor as listed in the image index.
        public let descriptor: Descriptor
        /// The platform manifest.
        public let manifest: ContainerizationOCI.Manifest
        /// The OCI image config for the platform.
        public let config: ContainerizationOCI.Image

        public init(descriptor: Descriptor, manifest: ContainerizationOCI.Manifest, config: ContainerizationOCI.Image) {
            self.descriptor = descriptor
            self.manifest = manifest
            self.config = config
        }
    }

    /// The image's description — its reference and index descriptor.
    public let config: ImageDescription

    /// The resolved index descriptor for the image.
    public let index: Descriptor

    /// The platform-specific variants contained in the image.
    public let variants: [Variant]

    /// The reference to show in human-facing listings, with default-registry
    /// information removed (e.g. `alpine` rather than `docker.io/library/alpine`).
    /// Computed by the caller, which has access to the system configuration.
    /// Defaults to the full ``name`` when not supplied.
    public let displayReference: String

    /// The creation date resolved from the OCI image config, if available.
    private let created: Date?

    // MARK: ManagedResource

    /// The unique identifier for this image. Identical to the image's index digest.
    public var id: String { config.digest }

    /// The user-facing reference (`name:tag`) for this image.
    public var name: String { config.reference }

    /// The time at which the image was created, resolved from the OCI image
    /// config. Falls back to the Unix epoch when no creation date is recorded.
    public var creationDate: Date { created ?? Date(timeIntervalSince1970: 0) }

    /// Key-value labels for this image, derived from the index descriptor's
    /// annotations. Returns an empty label set if the annotations fail
    /// ``ResourceLabels`` validation.
    public var labels: ResourceLabels {
        (try? ResourceLabels(config.descriptor.annotations ?? [:])) ?? ResourceLabels()
    }

    // MARK: Initialization

    /// Creates an image resource.
    ///
    /// - Parameters:
    ///   - config: The image's description (reference and index descriptor).
    ///   - index: The resolved index descriptor.
    ///   - variants: The per-platform variants contained in the image.
    ///   - created: The creation date resolved from the OCI image config, if any.
    ///   - displayReference: The denormalized reference for human-facing
    ///     listings. Defaults to the full reference when `nil`.
    public init(config: ImageDescription, index: Descriptor, variants: [Variant], created: Date? = nil, displayReference: String? = nil) {
        self.config = config
        self.index = index
        self.variants = variants
        self.created = created
        self.displayReference = displayReference ?? config.reference
    }
}

extension ImageResource {
    /// Creates an image resource from already-resolved index and manifest
    /// content.
    ///
    /// This initializer performs the variant resolution: it computes each
    /// platform variant's total size (manifest descriptor + config + layers)
    /// and derives the image's creation date from the earliest variant's OCI
    /// config `created` timestamp.
    ///
    /// - Parameters:
    ///   - config: The image's description (reference and index descriptor).
    ///   - index: The resolved index descriptor.
    ///   - manifests: The already-resolved per-platform manifest content.
    ///   - displayReference: The denormalized reference for human-facing
    ///     listings. Defaults to the full reference when `nil`.
    public init(config: ImageDescription, index: Descriptor, manifests: [ManifestContent], displayReference: String? = nil) {
        var variants: [Variant] = []
        var created: Date?
        for content in manifests {
            guard let platform = content.descriptor.platform else {
                continue
            }
            let size =
                content.descriptor.size + content.manifest.config.size
                + content.manifest.layers.reduce(0) { $0 + $1.size }
            variants.append(Variant(platform: platform, digest: content.descriptor.digest, size: size, config: content.config))
            // Use the earliest variant's creation timestamp as the image's date.
            if let createdString = content.config.created, let date = Self.parseCreated(createdString) {
                created = created.map { min($0, date) } ?? date
            }
        }
        self.init(config: config, index: index, variants: variants, created: created, displayReference: displayReference)
    }

    private static func parseCreated(_ value: String) -> Date? {
        let withFractional = ISO8601DateFormatter()
        withFractional.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
        if let date = withFractional.date(from: value) {
            return date
        }
        let formatter = ISO8601DateFormatter()
        formatter.formatOptions = [.withInternetDateTime]
        return formatter.date(from: value)
    }
}

extension ImageResource {
    /// Returns `true` if `name` is a syntactically valid image reference.
    public static func nameValid(_ name: String) -> Bool {
        (try? Reference.parse(name)) != nil
    }
}

// MARK: - Codable

extension ImageResource {
    enum CodingKeys: String, CodingKey {
        case id
        case name
        case creationDate
        case labels
        case configuration
        case index
        case variants
    }

    public func encode(to encoder: Encoder) throws {
        var container = encoder.container(keyedBy: CodingKeys.self)
        try container.encode(id, forKey: .id)
        try container.encode(name, forKey: .name)
        try container.encode(creationDate, forKey: .creationDate)
        try container.encode(labels, forKey: .labels)
        try container.encode(config, forKey: .configuration)
        try container.encode(index, forKey: .index)
        try container.encode(variants, forKey: .variants)
    }

    public init(from decoder: Decoder) throws {
        let container = try decoder.container(keyedBy: CodingKeys.self)
        self.config = try container.decode(ImageDescription.self, forKey: .configuration)
        self.index = try container.decode(Descriptor.self, forKey: .index)
        self.variants = try container.decode([Variant].self, forKey: .variants)
        self.created = try container.decodeIfPresent(Date.self, forKey: .creationDate)
        // `displayReference` is a display-only value and is not serialized.
        self.displayReference = self.config.reference
    }
}