ContainerRegistry: Define ImageDestination protocol

Author: euanh

Sources/ContainerRegistry/ImageDestination.swift

@@ -0,0 +1,105 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftContainerPlugin open source project
+//
+// Copyright (c) 2025 Apple Inc. and the SwiftContainerPlugin project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftContainerPlugin project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import struct Foundation.Data
+
+/// A destination, such as a registry, to which container images can be uploaded.
+public protocol ImageDestination {
+    /// Uploads a blob of unstructured data.
+    ///
+    /// - Parameters:
+    ///   - repository: Name of the destination repository.
+    ///   - mediaType: mediaType field for returned ContentDescriptor.
+    ///       On the wire, all blob uploads are `application/octet-stream'.
+    ///   - data: Object to be uploaded.
+    /// - Returns: An ContentDescriptor object representing the
+    ///            uploaded blob.
+    /// - Throws: If the upload fails.
+    func putBlob(
+        repository: ImageReference.Repository,
+        mediaType: String,
+        data: Data
+    ) async throws -> ContentDescriptor
+
+    /// Encodes and uploads a JSON object.
+    ///
+    /// - Parameters:
+    ///   - repository: Name of the destination repository.
+    ///   - mediaType: mediaType field for returned ContentDescriptor.
+    ///       On the wire, all blob uploads are `application/octet-stream'.
+    ///   - data: Object to be uploaded.
+    /// - Returns: An ContentDescriptor object representing the
+    ///            uploaded blob.
+    /// - Throws: If the blob cannot be encoded or the upload fails.
+    ///
+    ///  Some JSON objects, such as ImageConfiguration, are stored
+    /// in the registry as plain blobs with MIME type "application/octet-stream".
+    /// This function encodes the data parameter and uploads it as a generic blob.
+    func putBlob<Body: Encodable>(
+        repository: ImageReference.Repository,
+        mediaType: String,
+        data: Body
+    ) async throws -> ContentDescriptor
+
+    /// Checks whether a blob exists.
+    ///
+    /// - Parameters:
+    ///   - repository: Name of the destination repository.
+    ///   - digest: Digest of the requested blob.
+    /// - Returns: True if the blob exists, otherwise false.
+    /// - Throws: If the destination encounters an error.
+    func blobExists(
+        repository: ImageReference.Repository,
+        digest: ImageReference.Digest
+    ) async throws -> Bool
+
+    /// Encodes and uploads an image manifest.
+    ///
+    /// - Parameters:
+    ///   - repository: Name of the destination repository.
+    ///   - reference: Optional tag to apply to this manifest.
+    ///   - manifest: Manifest to be uploaded.
+    /// - Returns: An ContentDescriptor object representing the
+    ///            uploaded blob.
+    /// - Throws: If the blob cannot be encoded or the upload fails.
+    ///
+    /// Manifests are not treated as blobs by the distribution specification.
+    /// They have their own MIME types and are uploaded to different
+    /// registry endpoints than blobs.
+    func putManifest(
+        repository: ImageReference.Repository,
+        reference: (any ImageReference.Reference)?,
+        manifest: ImageManifest
+    ) async throws -> ContentDescriptor
+}
+
+extension ImageDestination {
+    /// Uploads a blob of unstructured data.
+    ///
+    /// - Parameters:
+    ///   - repository: Name of the destination repository.
+    ///   - mediaType: mediaType field for returned ContentDescriptor.
+    ///       On the wire, all blob uploads are `application/octet-stream'.
+    ///   - data: Object to be uploaded.
+    /// - Returns: An ContentDescriptor object representing the
+    ///            uploaded blob.
+    /// - Throws: If the upload fails.
+    public func putBlob(
+        repository: ImageReference.Repository,
+        mediaType: String = "application/octet-stream",
+        data: Data
+    ) async throws -> ContentDescriptor {
+        try await putBlob(repository: repository, mediaType: mediaType, data: data)
+    }
+}

Sources/ContainerRegistry/RegistryClient+ImageConfiguration.swift

@@ -28,7 +28,9 @@ extension RegistryClient {
         let data = try await getBlob(repository: image.repository, digest: digest)
         return try decoder.decode(ImageConfiguration.self, from: data)
     }
+}
 
+extension ImageDestination {
     /// Upload an image configuration record to the registry.
     /// - Parameters:
     ///   - image: Reference to the image associated with the record.

Sources/ContainerRegistry/RegistryClient.swift

@@ -374,3 +374,6 @@ extension RegistryClient {
 
 /// Make decoded registry errors throwable
 extension DistributionErrors: Error {}
+
+/// Images can be uploaded to a registry using a RegistryClient instance
+extension RegistryClient: ImageDestination {}

Sources/containertool/Extensions/RegistryClient+CopyBlobs.swift

@@ -25,7 +25,7 @@ extension RegistryClient {
     func copyBlob(
         digest: ImageReference.Digest,
         fromRepository sourceRepository: ImageReference.Repository,
-        toClient destClient: RegistryClient,
+        toClient destClient: ImageDestination,
         toRepository destRepository: ImageReference.Repository
     ) async throws {
         if try await destClient.blobExists(repository: destRepository, digest: digest) {

Sources/containertool/Extensions/RegistryClient+Layers.swift

@@ -37,25 +37,21 @@ extension RegistryClient {
             )
         }
     }
+}
 
-    typealias DiffID = ImageReference.Digest
-    struct ImageLayer {
-        var descriptor: ContentDescriptor
-        var diffID: DiffID
-    }
-
+extension ImageDestination {
     // A layer is a tarball, optionally compressed using gzip or zstd
     // See https://github.com/opencontainers/image-spec/blob/main/media-types.md
     func uploadLayer(
         repository: ImageReference.Repository,
         contents: [UInt8],
         mediaType: String = "application/vnd.oci.image.layer.v1.tar+gzip"
-    ) async throws -> ImageLayer {
+    ) async throws -> (descriptor: ContentDescriptor, diffID: ImageReference.Digest) {
         // The diffID is the hash of the unzipped layer tarball
         let diffID = ImageReference.Digest(of: contents)
         // The layer blob is the gzipped tarball;  the descriptor is the hash of this gzipped blob
         let blob = Data(gzip(contents))
         let descriptor = try await putBlob(repository: repository, mediaType: mediaType, data: blob)
-        return ImageLayer(descriptor: descriptor, diffID: diffID)
+        return (descriptor: descriptor, diffID: diffID)
     }
 }

Sources/containertool/Extensions/RegistryClient+publish.swift

@@ -18,11 +18,11 @@ import struct Foundation.URL
 import ContainerRegistry
 import Tar
 
-func publishContainerImage(
+func publishContainerImage<Destination: ImageDestination>(
     baseImage: ImageReference,
     destinationImage: ImageReference,
     source: RegistryClient?,
-    destination: RegistryClient,
+    destination: Destination,
     architecture: String,
     os: String,
     resources: [String],
@@ -64,7 +64,7 @@ func publishContainerImage(
 
     // MARK: Upload resource layers
 
-    var resourceLayers: [RegistryClient.ImageLayer] = []
+    var resourceLayers: [(descriptor: ContentDescriptor, diffID: ImageReference.Digest)] = []
     for resourceDir in resources {
         let resourceTardiff = try Archive().appendingRecursively(atPath: resourceDir).bytes
         let resourceLayer = try await destination.uploadLayer(