ContainerRegistry: Define ImageSource protocol

Author: euanh

Sources/ContainerRegistry/ImageSource.swift

@@ -0,0 +1,69 @@
+//===----------------------------------------------------------------------===//
+//
+// 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 source, such as a registry, from which container images can be fetched.
+public protocol ImageSource {
+    /// Fetches a blob of unstructured data.
+    ///
+    /// - Parameters:
+    ///   - repository: Name of the source repository.
+    ///   - digest: Digest of the blob.
+    /// - Returns: The downloaded data.
+    /// - Throws: If the blob download fails.
+    func getBlob(
+        repository: ImageReference.Repository,
+        digest: ImageReference.Digest
+    ) async throws -> Data
+
+    /// Fetches an image manifest.
+    ///
+    /// - Parameters:
+    ///   - repository: Name of the source repository.
+    ///   - reference: Tag or digest of the manifest to fetch.
+    /// - Returns: The downloaded manifest.
+    /// - Throws: If the download fails or the manifest cannot be decoded.
+    func getManifest(
+        repository: ImageReference.Repository,
+        reference: any ImageReference.Reference
+    ) async throws -> (ImageManifest, ContentDescriptor)
+
+    /// Fetches an image index.
+    ///
+    /// - Parameters:
+    ///   - repository: Name of the source repository.
+    ///   - reference: Tag or digest of the index to fetch.
+    /// - Returns: The downloaded index.
+    /// - Throws: If the download fails or the index cannot be decoded.
+    func getIndex(
+        repository: ImageReference.Repository,
+        reference: any ImageReference.Reference
+    ) async throws -> ImageIndex
+
+    /// Fetches an image configuration from the registry.
+    ///
+    /// - Parameters:
+    ///   - image: Reference to the image containing the record.
+    ///   - digest: Digest of the configuration object to fetch.
+    /// - Returns: The image confguration record.
+    /// - Throws: If the download fails or the configuration record cannot be decoded.
+    ///
+    /// Image configuration records are stored as blobs in the registry.  This function retrieves
+    /// the requested blob and tries to decode it as a configuration record.
+    func getImageConfiguration(
+        forImage image: ImageReference,
+        digest: ImageReference.Digest
+    ) async throws -> ImageConfiguration
+}

Sources/ContainerRegistry/RegistryClient+ImageConfiguration.swift

@@ -12,6 +12,8 @@
 //
 //===----------------------------------------------------------------------===//
 
+import class Foundation.JSONDecoder
+
 extension RegistryClient {
     /// Get an image configuration record from the registry.
     /// - Parameters:

Sources/ContainerRegistry/RegistryClient.swift

@@ -375,5 +375,5 @@ extension RegistryClient {
 /// Make decoded registry errors throwable
 extension DistributionErrors: Error {}
 
-/// Images can be uploaded to a registry using a RegistryClient instance
-extension RegistryClient: ImageDestination {}
+/// RegistryClient can both fetch and upload images
+extension RegistryClient: ImageSource, ImageDestination {}

Sources/containertool/Extensions/RegistryClient+CopyBlobs.swift

@@ -14,7 +14,7 @@
 
 import ContainerRegistry
 
-extension RegistryClient {
+extension ImageSource {
     /// Copies a blob from another registry to this one.
     /// - Parameters:
     ///   - digest: The digest of the blob to copy.

Sources/containertool/Extensions/RegistryClient+Layers.swift

@@ -15,10 +15,11 @@
 import struct Foundation.Data
 import ContainerRegistry
 
-extension RegistryClient {
-    func getImageManifest(forImage image: ImageReference, architecture: String) async throws -> (
-        ImageManifest, ContentDescriptor
-    ) {
+extension ImageSource {
+    public func getImageManifest(
+        forImage image: ImageReference,
+        architecture: String
+    ) async throws -> (ImageManifest, ContentDescriptor) {
         do {
             // Try to retrieve a manifest.   If the object with this reference is actually an index, the content-type will not match and
             // an error will be thrown.

Sources/containertool/Extensions/RegistryClient+publish.swift

@@ -18,10 +18,10 @@ import struct Foundation.URL
 import ContainerRegistry
 import Tar
 
-func publishContainerImage<Destination: ImageDestination>(
+func publishContainerImage<Source: ImageSource, Destination: ImageDestination>(
     baseImage: ImageReference,
     destinationImage: ImageReference,
-    source: RegistryClient?,
+    source: Source?,
     destination: Destination,
     architecture: String,
     os: String,