ContainerRegistry: Introduce Repository type

euanh · euanh · commit a685f2ef9bca · 2025-05-29T12:09:44.000+01:00
diff --git a/Sources/ContainerRegistry/AuthHandler.swift b/Sources/ContainerRegistry/AuthHandler.swift
@@ -158,7 +158,7 @@ public struct AuthHandler {
 
     public func auth(
         registry: URL,
-        repository: String,
+        repository: Repository,
         actions: [String],
         withScheme scheme: AuthChallenge,
         usingClient client: HTTPClient
diff --git a/Sources/ContainerRegistry/Blobs.swift b/Sources/ContainerRegistry/Blobs.swift
@@ -28,9 +28,7 @@ public func digest<D: DataProtocol>(of data: D) -> String {
 
 extension RegistryClient {
     // Internal helper method to initiate a blob upload in 'two shot' mode
-    func startBlobUploadSession(repository: String) async throws -> URL {
-        precondition(repository.count > 0, "repository must not be an empty string")
-
+    func startBlobUploadSession(repository: Repository) async throws -> URL {
         // Upload in "two shot" mode.
         // See https://github.com/opencontainers/distribution-spec/blob/main/spec.md#post-then-put
         // - POST to obtain a session ID.
@@ -67,8 +65,7 @@ extension RegistryClient {
 extension HTTPField.Name { static let dockerContentDigest = Self("Docker-Content-Digest")! }
 
 public extension RegistryClient {
-    func blobExists(repository: String, digest: String) async throws -> Bool {
-        precondition(repository.count > 0, "repository must not be an empty string")
+    func blobExists(repository: Repository, digest: String) async throws -> Bool {
         precondition(digest.count > 0)
 
         do {
@@ -87,8 +84,7 @@ public extension RegistryClient {
     ///   - digest: Digest of the blob.
     /// - Returns: The downloaded data.
     /// - Throws: If the blob download fails.
-    func getBlob(repository: String, digest: String) async throws -> Data {
-        precondition(repository.count > 0, "repository must not be an empty string")
+    func getBlob(repository: Repository, digest: String) async throws -> Data {
         precondition(digest.count > 0, "digest must not be an empty string")
 
         return try await executeRequestThrowing(
@@ -110,8 +106,7 @@ public extension RegistryClient {
     /// in the registry as plain blobs with MIME type "application/octet-stream".
     /// This function attempts to decode the received data without reference
     /// to the MIME type.
-    func getBlob<Response: Decodable>(repository: String, digest: String) async throws -> Response {
-        precondition(repository.count > 0, "repository must not be an empty string")
+    func getBlob<Response: Decodable>(repository: Repository, digest: String) async throws -> Response {
         precondition(digest.count > 0, "digest must not be an empty string")
 
         return try await executeRequestThrowing(
@@ -132,11 +127,9 @@ public extension RegistryClient {
     /// - Returns: An ContentDescriptor object representing the
     ///            uploaded blob.
     /// - Throws: If the blob cannot be encoded or the upload fails.
-    func putBlob(repository: String, mediaType: String = "application/octet-stream", data: Data) async throws
+    func putBlob(repository: Repository, mediaType: String = "application/octet-stream", data: Data) async throws
         -> ContentDescriptor
     {
-        precondition(repository.count > 0, "repository must not be an empty string")
-
         // Ask the server to open a session and tell us where to upload our data
         let location = try await startBlobUploadSession(repository: repository)
 
@@ -179,7 +172,7 @@ public extension RegistryClient {
     ///  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: String, mediaType: String = "application/octet-stream", data: Body)
+    func putBlob<Body: Encodable>(repository: Repository, mediaType: String = "application/octet-stream", data: Body)
         async throws -> ContentDescriptor
     {
         let encoded = try encoder.encode(data)
diff --git a/Sources/ContainerRegistry/ImageReference.swift b/Sources/ContainerRegistry/ImageReference.swift
@@ -14,7 +14,10 @@
 
 import RegexBuilder
 
-enum ReferenceError: Error { case unexpected(String) }
+public enum ReferenceError: Error {
+    case emptyReference
+    case unexpected(String)
+}
 
 // https://github.com/distribution/distribution/blob/v2.7.1/reference/reference.go
 // Split the image reference into a registry and a name part.
@@ -47,12 +50,36 @@ func splitName(_ name: String) throws -> (String, String) {
     return (String(tagSplit[0]), String(tagSplit[1]))
 }
 
+/// Repository refers a repository (image namespace) on a container registry
+public struct Repository: Sendable, Equatable, CustomStringConvertible, CustomDebugStringConvertible {
+    var value: String
+
+    public init(_ rawValue: String) throws {
+        // Reference handling in github.com/distribution reports empty and uppercase as specific errors.
+        // All other errors caused are reported as generic format errors.
+        guard rawValue.count > 0 else {
+            throw ReferenceError.emptyReference
+        }
+
+        value = rawValue
+    }
+
+    public var description: String {
+        value
+    }
+
+    /// Printable description of an ImageReference in a form suitable for debugging.
+    public var debugDescription: String {
+        "Repository(\(value))"
+    }
+}
+
 /// ImageReference points to an image stored on a container registry
 public struct ImageReference: Sendable, Equatable, CustomStringConvertible, CustomDebugStringConvertible {
     /// The registry which contains this image
     public var registry: String
     /// The repository which contains this image
-    public var repository: String
+    public var repository: Repository
     /// The tag identifying the image.
     public var reference: String
 
@@ -72,21 +99,23 @@ public struct ImageReference: Sendable, Equatable, CustomStringConvertible, Cust
         // moby/moby assumes that these names refer to images in `library`: `library/swift` or `library/swift:slim`.
         // This special case only applies when using Docker Hub, so `example.com/swift` is not expanded `example.com/library/swift`
         if self.registry == "index.docker.io" && !repository.contains("/") {
-            self.repository = "library/\(repository)"
+            self.repository = try Repository("library/\(repository)")
         } else {
-            self.repository = repository
+            self.repository = try Repository(repository)
         }
         self.reference = reference
     }
 
     /// Creates an ImageReference from separate registry, repository and reference strings.
+    /// Used only in tests.
     /// - Parameters:
     ///   - registry: The registry which stores the image data.
     ///   - repository: The repository within the registry which holds the image.
     ///   - reference: The tag identifying the image.
-    public init(registry: String, repository: String, reference: String) {
+    /// - Throws: If the image reference is invalid.
+    init(registry: String, repository: String, reference: String) throws {
         self.registry = registry
-        self.repository = repository
+        self.repository = try Repository(repository)
         self.reference = reference
     }
 
diff --git a/Sources/ContainerRegistry/Manifests.swift b/Sources/ContainerRegistry/Manifests.swift
@@ -13,10 +13,9 @@
 //===----------------------------------------------------------------------===//
 
 public extension RegistryClient {
-    func putManifest(repository: String, reference: String, manifest: ImageManifest) async throws -> String {
+    func putManifest(repository: Repository, reference: String, manifest: ImageManifest) async throws -> String {
         // See https://github.com/opencontainers/distribution-spec/blob/main/spec.md#pushing-manifests
-        precondition(repository.count > 0, "repository must not be an empty string")
-        precondition(reference.count > 0, "reference must not be an empty string")
+        precondition("\(reference)".count > 0, "reference must not be an empty string")
 
         let httpResponse = try await executeRequestThrowing(
             // All blob uploads have Content-Type: application/octet-stream on the wire, even if mediatype is different
@@ -41,9 +40,8 @@ public extension RegistryClient {
             .absoluteString
     }
 
-    func getManifest(repository: String, reference: String) async throws -> ImageManifest {
+    func getManifest(repository: Repository, reference: String) async throws -> ImageManifest {
         // See https://github.com/opencontainers/distribution-spec/blob/main/spec.md#pulling-manifests
-        precondition(repository.count > 0, "repository must not be an empty string")
         precondition(reference.count > 0, "reference must not be an empty string")
 
         return try await executeRequestThrowing(
@@ -60,8 +58,7 @@ public extension RegistryClient {
         .data
     }
 
-    func getIndex(repository: String, reference: String) async throws -> ImageIndex {
-        precondition(repository.count > 0, "repository must not be an empty string")
+    func getIndex(repository: Repository, reference: String) async throws -> ImageIndex {
         precondition(reference.count > 0, "reference must not be an empty string")
 
         return try await executeRequestThrowing(
diff --git a/Sources/ContainerRegistry/RegistryClient.swift b/Sources/ContainerRegistry/RegistryClient.swift
@@ -127,7 +127,7 @@ extension URL {
     ///   - repository: The name of the repository.   May include path separators.
     ///   - endpoint: The distribution endpoint e.g. "tags/list"
     /// - Returns: A fully-qualified URL for the endpoint.
-    func distributionEndpoint(forRepository repository: String, andEndpoint endpoint: String) -> URL {
+    func distributionEndpoint(forRepository repository: Repository, andEndpoint endpoint: String) -> URL {
         self.appendingPathComponent("/v2/\(repository)/\(endpoint)")
     }
 }
@@ -141,7 +141,7 @@ extension RegistryClient {
         }
 
         var method: HTTPRequest.Method  // HTTP method
-        var repository: String  // Repository path on the registry
+        var repository: Repository  // Repository path on the registry
         var destination: Destination  // Destination of the operation: can be a subpath or remote URL
         var actions: [String]  // Actions required by this operation
         var accepting: [String] = []  // Acceptable response types
@@ -156,7 +156,7 @@ extension RegistryClient {
 
         // Convenience constructors
         static func get(
-            _ repository: String,
+            _ repository: Repository,
             path: String,
             actions: [String]? = nil,
             accepting: [String] = [],
@@ -173,7 +173,7 @@ extension RegistryClient {
         }
 
         static func get(
-            _ repository: String,
+            _ repository: Repository,
             url: URL,
             actions: [String]? = nil,
             accepting: [String] = [],
@@ -190,7 +190,7 @@ extension RegistryClient {
         }
 
         static func head(
-            _ repository: String,
+            _ repository: Repository,
             path: String,
             actions: [String]? = nil,
             accepting: [String] = [],
@@ -208,7 +208,7 @@ extension RegistryClient {
 
         /// This handles the 'put' case where the registry gives us a location URL which we must not alter, aside from adding the digest to it
         static func put(
-            _ repository: String,
+            _ repository: Repository,
             url: URL,
             actions: [String]? = nil,
             accepting: [String] = [],
@@ -225,7 +225,7 @@ extension RegistryClient {
         }
 
         static func put(
-            _ repository: String,
+            _ repository: Repository,
             path: String,
             actions: [String]? = nil,
             accepting: [String] = [],
@@ -242,7 +242,7 @@ extension RegistryClient {
         }
 
         static func post(
-            _ repository: String,
+            _ repository: Repository,
             path: String,
             actions: [String]? = nil,
             accepting: [String] = [],
diff --git a/Sources/ContainerRegistry/Tags.swift b/Sources/ContainerRegistry/Tags.swift
@@ -13,10 +13,8 @@
 //===----------------------------------------------------------------------===//
 
 public extension RegistryClient {
-    func getTags(repository: String) async throws -> Tags {
+    func getTags(repository: Repository) async throws -> Tags {
         // See https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-tags
-        precondition(repository.count > 0, "repository must not be an empty string")
-
         return try await executeRequestThrowing(.get(repository, path: "tags/list"), decodingErrors: [.notFound]).data
     }
 }
diff --git a/Sources/containertool/Extensions/RegistryClient+CopyBlobs.swift b/Sources/containertool/Extensions/RegistryClient+CopyBlobs.swift
@@ -24,9 +24,9 @@ extension RegistryClient {
     /// - Throws: If the copy cannot be completed.
     func copyBlob(
         digest: String,
-        fromRepository sourceRepository: String,
+        fromRepository sourceRepository: Repository,
         toClient destClient: RegistryClient,
-        toRepository destRepository: String
+        toRepository destRepository: Repository
     ) async throws {
         if try await destClient.blobExists(repository: destRepository, digest: digest) {
             log("Layer \(digest): already exists")
diff --git a/Sources/containertool/Extensions/RegistryClient+Layers.swift b/Sources/containertool/Extensions/RegistryClient+Layers.swift
@@ -45,7 +45,7 @@ extension RegistryClient {
     // 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: String,
+        repository: Repository,
         contents: [UInt8],
         mediaType: String = "application/vnd.oci.image.layer.v1.tar+gzip"
     ) async throws -> ImageLayer {
diff --git a/Tests/ContainerRegistryTests/ImageReferenceTests.swift b/Tests/ContainerRegistryTests/ImageReferenceTests.swift
@@ -17,7 +17,7 @@ import Testing
 
 struct ReferenceTestCase: Sendable {
     var reference: String
-    var expected: ImageReference?
+    var expected: ImageReference
 }
 
 struct ReferenceTests {
@@ -26,15 +26,15 @@ struct ReferenceTests {
         // in the default registry.
         ReferenceTestCase(
             reference: "localhost",
-            expected: ImageReference(registry: "default", repository: "localhost", reference: "latest")
+            expected: try! ImageReference(registry: "default", repository: "localhost", reference: "latest")
         ),
         ReferenceTestCase(
             reference: "example.com",
-            expected: ImageReference(registry: "default", repository: "example.com", reference: "latest")
+            expected: try! ImageReference(registry: "default", repository: "example.com", reference: "latest")
         ),
         ReferenceTestCase(
             reference: "example:1234",
-            expected: ImageReference(registry: "default", repository: "example", reference: "1234")
+            expected: try! ImageReference(registry: "default", repository: "example", reference: "1234")
         ),
 
         // If a reference contains a '/' *and* the component before the '/' looks like a
@@ -45,44 +45,44 @@ struct ReferenceTests {
         // "localhost" is a special case.
         ReferenceTestCase(
             reference: "localhost/foo",
-            expected: ImageReference(registry: "localhost", repository: "foo", reference: "latest")
+            expected: try! ImageReference(registry: "localhost", repository: "foo", reference: "latest")
         ),
         ReferenceTestCase(
             reference: "localhost:1234/foo",
-            expected: ImageReference(registry: "localhost:1234", repository: "foo", reference: "latest")
+            expected: try! ImageReference(registry: "localhost:1234", repository: "foo", reference: "latest")
         ),
         ReferenceTestCase(
             reference: "example.com/foo",
-            expected: ImageReference(registry: "example.com", repository: "foo", reference: "latest")
+            expected: try! ImageReference(registry: "example.com", repository: "foo", reference: "latest")
         ),
         ReferenceTestCase(
             reference: "example.com:1234/foo",
-            expected: ImageReference(registry: "example.com:1234", repository: "foo", reference: "latest")
+            expected: try! ImageReference(registry: "example.com:1234", repository: "foo", reference: "latest")
         ),
         ReferenceTestCase(
             reference: "example.com:1234/foo:bar",
-            expected: ImageReference(registry: "example.com:1234", repository: "foo", reference: "bar")
+            expected: try! ImageReference(registry: "example.com:1234", repository: "foo", reference: "bar")
         ),
 
         // If the part before the '/' does not look like a hostname, the whole reference
         // is interpreted as a repository name in the default registry.
         ReferenceTestCase(
             reference: "local/foo",
-            expected: ImageReference(registry: "default", repository: "local/foo", reference: "latest")
+            expected: try! ImageReference(registry: "default", repository: "local/foo", reference: "latest")
         ),
         ReferenceTestCase(
             reference: "example/foo",
-            expected: ImageReference(registry: "default", repository: "example/foo", reference: "latest")
+            expected: try! ImageReference(registry: "default", repository: "example/foo", reference: "latest")
         ),
         ReferenceTestCase(
             reference: "example/foo:1234",
-            expected: ImageReference(registry: "default", repository: "example/foo", reference: "1234")
+            expected: try! ImageReference(registry: "default", repository: "example/foo", reference: "1234")
         ),
 
         // Distribution spec tests
         ReferenceTestCase(
             reference: "example.com/foo@sha256:0123456789abcdef01234567890abcdef",
-            expected: ImageReference(
+            expected: try! ImageReference(
                 registry: "example.com",
                 repository: "foo",
                 reference: "sha256:0123456789abcdef01234567890abcdef"
@@ -92,11 +92,11 @@ struct ReferenceTests {
         // This example goes against the distribution spec's regular expressions but matches observed client behaviour
         ReferenceTestCase(
             reference: "foo:1234/bar:1234",
-            expected: ImageReference(registry: "foo:1234", repository: "bar", reference: "1234")
+            expected: try! ImageReference(registry: "foo:1234", repository: "bar", reference: "1234")
         ),
         ReferenceTestCase(
             reference: "localhost/foo:1234/bar:1234",
-            expected: ImageReference(registry: "localhost", repository: "foo", reference: "1234/bar:1234")
+            expected: try! ImageReference(registry: "localhost", repository: "foo", reference: "1234/bar:1234")
         ),
     ]
 
diff --git a/Tests/ContainerRegistryTests/SmokeTests.swift b/Tests/ContainerRegistryTests/SmokeTests.swift

Original file line number	Diff line number	Diff line change
`@@ -13,10 +13,8 @@`
`13`	`13`	`//===----------------------------------------------------------------------===//`
`14`	`14`
`15`	`15`	`public extension RegistryClient {`
`16`		`- func getTags(repository: String) async throws -> Tags {`
	`16`	`+ func getTags(repository: Repository) async throws -> Tags {`
`17`	`17`	`// See https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-tags`
`18`		`- precondition(repository.count > 0, "repository must not be an empty string")`
`19`		`-`
`20`	`18`	`return try await executeRequestThrowing(.get(repository, path: "tags/list"), decodingErrors: [.notFound]).data`
`21`	`19`	`}`
`22`	`20`	`}`