ContainerRegistry: Provide ContentDescriptors for manifests (#146)

Motivation
----------

In a multi-arch image, several architecture-specific manifests are
grouped together under the same
[index](https://github.com/opencontainers/image-spec/blob/v1.0.1/image-index.md).
The index has a list of [content
descriptors](https://github.com/opencontainers/image-spec/blob/v1.0.1/descriptor.md#properties)
pointing to the manifests.

Currently, `containertool` creates single-architecture images for which
the root object is a manifest. Returning a content descriptor for the
manifest allows it to create an index which points to the manifest.

On its own this does not allow `containertool` to create multi-arch
images, but it opens that possibility for the future. It is a necessary
towards being able to write [container images to
disk](https://github.com/opencontainers/image-spec/blob/v1.0.1/image-layout.md).

Modifications
-------------

* Return a ContentDescriptor from getManifest(), in addition to the
manifest object
* Return a ContentDescriptor from putManifest()

Result
------

`containertool` can retrieve a `ContentDescriptor` for a manifest it has
written or fetched.

Test Plan
---------

Existing tests have been updated to match the new signatures and
continue to pass.

Author: euanh

Sources/ContainerRegistry/ImageManifest+Digest.swift

@@ -15,39 +15,39 @@
 public extension RegistryClient {
     func putManifest(
         repository: ImageReference.Repository,
-        reference: any ImageReference.Reference,
+        reference: (any ImageReference.Reference)? = nil,
         manifest: ImageManifest
-    ) async throws -> String {
+    ) async throws -> ContentDescriptor {
         // See https://github.com/opencontainers/distribution-spec/blob/main/spec.md#pushing-manifests
-        let httpResponse = try await executeRequestThrowing(
-            // All blob uploads have Content-Type: application/octet-stream on the wire, even if mediatype is different
+
+        let encoded = try encoder.encode(manifest)
+        let digest = digest(of: encoded)
+        let mediaType = manifest.mediaType ?? "application/vnd.oci.image.manifest.v1+json"
+
+        let _ = try await executeRequestThrowing(
             .put(
                 repository,
-                path: "manifests/\(reference)",
-                contentType: manifest.mediaType ?? "application/vnd.oci.image.manifest.v1+json"
+                path: "manifests/\(reference ?? digest)",
+                contentType: mediaType
             ),
-            uploading: manifest,
+            uploading: encoded,
             expectingStatus: .created,
             decodingErrors: [.notFound]
         )
 
-        // The distribution spec says the response MUST contain a Location header
-        // providing a URL from which the saved manifest can be downloaded.
-        // However some registries return URLs which cannot be fetched, and
-        // ECR does not set this header at all.
-        // If the header is not present, create a suitable value.
-        // https://github.com/opencontainers/distribution-spec/blob/main/spec.md#pulling-manifests
-        return httpResponse.response.headerFields[.location]
-            ?? registryURL.distributionEndpoint(forRepository: repository, andEndpoint: "manifests/\(manifest.digest)")
-            .absoluteString
+        return ContentDescriptor(
+            mediaType: mediaType,
+            digest: "\(digest)",
+            size: Int64(encoded.count)
+        )
     }
 
     func getManifest(
         repository: ImageReference.Repository,
         reference: any ImageReference.Reference
-    ) async throws -> ImageManifest {
+    ) async throws -> (ImageManifest, ContentDescriptor) {
         // See https://github.com/opencontainers/distribution-spec/blob/main/spec.md#pulling-manifests
-        let (data, _) = try await executeRequestThrowing(
+        let (data, response) = try await executeRequestThrowing(
             .get(
                 repository,
                 path: "manifests/\(reference)",
@@ -58,7 +58,14 @@ public extension RegistryClient {
             ),
             decodingErrors: [.notFound]
         )
-        return try decoder.decode(ImageManifest.self, from: data)
+        return (
+            try decoder.decode(ImageManifest.self, from: data),
+            ContentDescriptor(
+                mediaType: response.headerFields[.contentType] ?? "application/vnd.oci.image.manifest.v1+json",
+                digest: "\(digest(of: data))",
+                size: Int64(data.count)
+            )
+        )
     }
 
     func getIndex(

Sources/ContainerRegistry/Manifests.swift

@@ -16,10 +16,9 @@ import struct Foundation.Data
 import ContainerRegistry
 
 extension RegistryClient {
-    func getImageManifest(forImage image: ImageReference, architecture: String) async throws -> ImageManifest {
-        // We pushed the amd64 tag but it points to a single-architecture index, not directly to a manifest
-        // if we get an index we should get a manifest, otherwise we might get a manifest directly
-
+    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+Layers.swift

@@ -249,12 +249,13 @@ extension RegistryClient {
 
         let baseImageManifest: ImageManifest
         let baseImageConfiguration: ImageConfiguration
+        let baseImageDescriptor: ContentDescriptor
         if let source {
-            baseImageManifest = try await source.getImageManifest(
+            (baseImageManifest, baseImageDescriptor) = try await source.getImageManifest(
                 forImage: baseImage,
                 architecture: architecture
             )
-            log("Found base image manifest: \(baseImageManifest.digest)")
+            try log("Found base image manifest: \(ImageReference.Digest(baseImageDescriptor.digest))")
 
             baseImageConfiguration = try await source.getImageConfiguration(
                 forImage: baseImage,
@@ -368,22 +369,25 @@ extension RegistryClient {
 
         // MARK: Upload application manifest
 
+        let manifestDescriptor = try await self.putManifest(
+            repository: destinationImage.repository,
+            reference: destinationImage.reference,
+            manifest: manifest
+        )
+
+        if verbose {
+            log("manifest: \(manifestDescriptor.digest) (\(manifestDescriptor.size) bytes)")
+        }
+
         // Use the manifest's digest if the user did not provide a human-readable tag
         // To support multiarch images, we should also create an an index pointing to
         // this manifest.
         let reference: ImageReference.Reference
         if let tag {
             reference = try ImageReference.Tag(tag)
         } else {
-            reference = manifest.digest
+            reference = try ImageReference.Digest(manifestDescriptor.digest)
         }
-        let location = try await self.putManifest(
-            repository: destinationImage.repository,
-            reference: destinationImage.reference,
-            manifest: manifest
-        )
-
-        if verbose { log(location) }
 
         var result = destinationImage
         result.reference = reference

Sources/containertool/containertool.swift

@@ -148,7 +148,10 @@ struct SmokeTests {
             manifest: test_manifest
         )
 
-        let manifest = try await client.getManifest(repository: repository, reference: ImageReference.Tag("latest"))
+        let (manifest, _) = try await client.getManifest(
+            repository: repository,
+            reference: ImageReference.Tag("latest")
+        )
         #expect(manifest.schemaVersion == 2)
         #expect(manifest.config.mediaType == "application/vnd.docker.container.image.v1+json")
         #expect(manifest.layers.count == 1)
@@ -181,15 +184,14 @@ struct SmokeTests {
             layers: [image_descriptor]
         )
 
-        let _ = try await client.putManifest(
+        let descriptor = try await client.putManifest(
             repository: repository,
-            reference: test_manifest.digest,
             manifest: test_manifest
         )
 
-        let manifest = try await client.getManifest(
+        let (manifest, _) = try await client.getManifest(
             repository: repository,
-            reference: test_manifest.digest
+            reference: ImageReference.Digest(descriptor.digest)
         )
         #expect(manifest.schemaVersion == 2)
         #expect(manifest.config.mediaType == "application/vnd.docker.container.image.v1+json")