Add content subcommand

This command can be used to interact with the content store XPC via simple commands.
Since many container tools are written in Go, it's not easy to interact with the XPC service from other tools.
Go has good support for unix domain sockets, but Mach ports (and XPC) are another story.

The content store is very useful to enable incremental image loading.
The closest alternative ("container image load") requires materialization of all blobs in a tar file.
With the content store, we can check which blobs are already available, and only load missing ones.
This will enable faster development workflows in tools like rules_img: https://github.com/bazel-contrib/rules_img.

A similar move is being made in Docker. The containerd content store used to be limited to the containerd socket.
This upstream issue will expose the containerd content store directly via Docker: moby/moby#44369

Author: malt3

Sources/ContainerCommands/Application.swift

@@ -192,12 +192,14 @@ public struct Application: AsyncParsableCommand {
         guard #available(macOS 26, *) else {
             return [
                 BuilderCommand.self,
+                ContentCommand.self,
                 SystemCommand.self,
             ]
         }
 
         return [
             BuilderCommand.self,
+            ContentCommand.self,
             NetworkCommand.self,
             SystemCommand.self,
         ]

Sources/ContainerCommands/Content/ContentCat.swift

@@ -0,0 +1,63 @@
+//===----------------------------------------------------------------------===//
+// Copyright © 2025 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 ArgumentParser
+import ContainerClient
+import ContainerImagesServiceClient
+import ContainerizationError
+import Foundation
+
+extension Application {
+    public struct ContentCat: AsyncParsableCommand {
+        public init() {}
+
+        public static let configuration = CommandConfiguration(
+            commandName: "cat",
+            abstract: "Output the contents of a blob from the content store"
+        )
+
+        @OptionGroup
+        var global: Flags.Global
+
+        @Option(name: .shortAndLong, help: "Path to write blob content (writes to stdout if not specified)")
+        var output: String?
+
+        @Argument(help: "Blob digest to output")
+        var digest: String
+
+        public func run() async throws {
+            let client = RemoteContentStoreClient()
+            guard let content = try await client.get(digest: digest) else {
+                throw ContainerizationError(.notFound, message: "blob \(digest)")
+            }
+
+            let data = try content.data()
+
+            if let outputPath = output {
+                let outputURL = URL(fileURLWithPath: outputPath)
+                try data.write(to: outputURL)
+
+                let formatter = ByteCountFormatter()
+                formatter.countStyle = .file
+                let formattedSize = formatter.string(fromByteCount: Int64(data.count))
+
+                print("Wrote \(formattedSize) to \(outputPath)")
+            } else {
+                FileHandle.standardOutput.write(data)
+            }
+        }
+    }
+}

Sources/ContainerCommands/Content/ContentCommand.swift

@@ -0,0 +1,34 @@
+//===----------------------------------------------------------------------===//
+// Copyright © 2025 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 ArgumentParser
+
+extension Application {
+    public struct ContentCommand: AsyncParsableCommand {
+        public init() {}
+
+        public static let configuration = CommandConfiguration(
+            commandName: "content",
+            abstract: "Low-level content store operations",
+            subcommands: [
+                ContentHead.self,
+                ContentDelete.self,
+                ContentCat.self,
+                ContentIngest.self,
+            ]
+        )
+    }
+}

Sources/ContainerCommands/Content/ContentDelete.swift

@@ -0,0 +1,56 @@
+//===----------------------------------------------------------------------===//
+// Copyright © 2025 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 ArgumentParser
+import ContainerClient
+import ContainerImagesServiceClient
+import ContainerizationError
+import Foundation
+
+extension Application {
+    public struct ContentDelete: AsyncParsableCommand {
+        public init() {}
+
+        public static let configuration = CommandConfiguration(
+            commandName: "delete",
+            abstract: "Remove a blob from the content store",
+            aliases: ["rm"]
+        )
+
+        @OptionGroup
+        var global: Flags.Global
+
+        @Argument(help: "Blob digest to delete")
+        var digest: String
+
+        public func run() async throws {
+            let client = RemoteContentStoreClient()
+            let digestWithoutPrefix = digest.replacingOccurrences(of: "sha256:", with: "")
+            let (deleted, size) = try await client.delete(digests: [digestWithoutPrefix])
+
+            guard deleted.contains(digestWithoutPrefix) else {
+                throw ContainerizationError(.notFound, message: "blob \(digest)")
+            }
+
+            let formatter = ByteCountFormatter()
+            formatter.countStyle = .file
+            let freed = formatter.string(fromByteCount: Int64(size))
+
+            print("Deleted \(digest)")
+            print("Reclaimed \(freed) in disk space")
+        }
+    }
+}

Sources/ContainerCommands/Content/ContentHead.swift

@@ -0,0 +1,68 @@
+//===----------------------------------------------------------------------===//
+// Copyright © 2025 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 ArgumentParser
+import ContainerClient
+import ContainerImagesServiceClient
+import ContainerizationError
+import Foundation
+
+extension Application {
+    public struct ContentHead: AsyncParsableCommand {
+        public init() {}
+
+        public static let configuration = CommandConfiguration(
+            commandName: "head",
+            abstract: "Display metadata about a blob in the content store"
+        )
+
+        @OptionGroup
+        var global: Flags.Global
+
+        @Option(name: .long, help: "Format of the output (json or table)")
+        var format: ListFormat = .table
+
+        @Argument(help: "Blob digest to inspect")
+        var digest: String
+
+        public func run() async throws {
+            let client = RemoteContentStoreClient()
+            guard let content = try await client.get(digest: digest) else {
+                throw ContainerizationError(.notFound, message: "blob \(digest)")
+            }
+
+            let size = try content.size()
+
+            if format == .json {
+                struct BlobInfo: Codable {
+                    let digest: String
+                    let size: UInt64
+                }
+                let info = BlobInfo(digest: digest, size: size)
+                let encoder = JSONEncoder()
+                encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+                let data = try encoder.encode(info)
+                guard let jsonString = String(data: data, encoding: .utf8) else {
+                    throw ContainerizationError(.internalError, message: "Failed to encode JSON output")
+                }
+                print(jsonString)
+            } else {
+                // Machine-readable default: digest-size
+                print("\(digest)-\(size)")
+            }
+        }
+    }
+}

Sources/ContainerCommands/Content/ContentIngest.swift

@@ -0,0 +1,140 @@
+//===----------------------------------------------------------------------===//
+// Copyright © 2025 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 ArgumentParser
+import ContainerClient
+import ContainerImagesServiceClient
+import ContainerizationError
+import Crypto
+import Foundation
+
+extension Application {
+    public struct ContentIngest: AsyncParsableCommand {
+        public init() {}
+
+        public static let configuration = CommandConfiguration(
+            commandName: "ingest",
+            abstract: "Add a blob to the content store from a file or stdin"
+        )
+
+        @OptionGroup
+        var global: Flags.Global
+
+        @Option(name: .shortAndLong, help: "Path to read content from (reads from stdin if not specified)")
+        var input: String?
+
+        @Option(name: .shortAndLong, help: "Expected blob digest (computed and verified if not provided)")
+        var digest: String?
+
+        public func run() async throws {
+            let client = RemoteContentStoreClient()
+            let inputPath = self.input
+            let expectedDigest = self.digest
+
+            // Show hint when reading from stdin
+            if inputPath == nil {
+                FileHandle.standardError.write(Data("Reading from stdin...\n".utf8))
+            }
+
+            // Start a new ingest session
+            let (sessionId, ingestDir) = try await client.newIngestSession()
+
+            // Hash the data as we ingest it
+            var hasher = SHA256()
+            var ingestedDigest: String = ""
+
+            do {
+                // Determine temporary digest for filename (use expected or placeholder)
+                let tempDigestForFilename: String
+                if let expected = expectedDigest {
+                    tempDigestForFilename = expected.replacingOccurrences(of: "sha256:", with: "")
+                } else {
+                    // Use a temporary name, we'll compute the real digest
+                    tempDigestForFilename = "temp-\(UUID().uuidString)"
+                }
+
+                let blobPath = ingestDir.appendingPathComponent(tempDigestForFilename)
+
+                // Open source handle
+                let sourceHandle: FileHandle
+                if let inputPath = inputPath {
+                    let inputURL = URL(fileURLWithPath: inputPath)
+                    sourceHandle = try FileHandle(forReadingFrom: inputURL)
+                } else {
+                    sourceHandle = FileHandle.standardInput
+                }
+                defer {
+                    if inputPath != nil {
+                        try? sourceHandle.close()
+                    }
+                }
+
+                // Create destination file
+                FileManager.default.createFile(atPath: blobPath.path, contents: nil)
+                let destHandle = try FileHandle(forWritingTo: blobPath)
+                defer { try? destHandle.close() }
+
+                // Stream data while computing hash
+                let bufferSize = 1024 * 1024 // 1 MB
+                while let chunk = try sourceHandle.read(upToCount: bufferSize), !chunk.isEmpty {
+                    hasher.update(data: chunk)
+                    try destHandle.write(contentsOf: chunk)
+                }
+
+                // Compute final digest
+                let digestValue = hasher.finalize()
+                ingestedDigest = "sha256:\(digestValue.map { String(format: "%02x", $0) }.joined())"
+
+                // Verify against expected digest if provided
+                if let expectedDigest = expectedDigest {
+                    if ingestedDigest != expectedDigest {
+                        // Digest mismatch - cancel ingest
+                        try await client.cancelIngestSession(sessionId)
+                        throw ContainerizationError(
+                            .invalidArgument,
+                            message: "Digest mismatch: expected \(expectedDigest), got \(ingestedDigest)"
+                        )
+                    }
+                }
+
+                // If we used a temp filename, rename it to the correct digest
+                if tempDigestForFilename.starts(with: "temp-") {
+                    let correctDigestFilename = ingestedDigest.replacingOccurrences(of: "sha256:", with: "")
+                    let correctBlobPath = ingestDir.appendingPathComponent(correctDigestFilename)
+                    try FileManager.default.moveItem(at: blobPath, to: correctBlobPath)
+                }
+
+                // Complete the ingest session
+                let ingested = try await client.completeIngestSession(sessionId)
+                let digestWithoutPrefix = ingestedDigest.replacingOccurrences(of: "sha256:", with: "")
+
+                guard ingested.contains(digestWithoutPrefix) else {
+                    throw ContainerizationError(
+                        .internalError,
+                        message: "ingested blob not found in content store"
+                    )
+                }
+
+                print("Ingested \(ingestedDigest)")
+
+            } catch {
+                // Cancel the ingest session on any error
+                try? await client.cancelIngestSession(sessionId)
+                throw error
+            }
+        }
+    }
+}