Add container system df command for disk usage reporting

Sources/ContainerClient/Core/ClientDiskUsage.swift

@@ -0,0 +1,40 @@
+//===----------------------------------------------------------------------===//
+// 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 ContainerXPC
+import ContainerizationError
+import Foundation
+
+/// Client API for disk usage operations
+public struct ClientDiskUsage {
+    static let serviceIdentifier = "com.apple.container.apiserver"
+
+    /// Get disk usage statistics for all resource types
+    public static func get() async throws -> DiskUsageStats {
+        let client = XPCClient(service: serviceIdentifier)
+        let message = XPCMessage(route: .systemDiskUsage)
+        let reply = try await client.send(message)
+
+        guard let responseData = reply.dataNoCopy(key: .diskUsageStats) else {
+            throw ContainerizationError(
+                .internalError,
+                message: "Invalid response from server: missing disk usage data"
+            )
+        }
+
+        return try JSONDecoder().decode(DiskUsageStats.self, from: responseData)
+    }
+}

Sources/ContainerClient/Core/ClientImage.swift

@@ -289,10 +289,30 @@ extension ClientImage {
         let request = newRequest(.imagePrune)
         let response = try await client.send(request)
         let digests = try response.digests()
-        let size = response.uint64(key: .size)
+        let size = response.uint64(key: .imageSize)
         return (digests, size)
     }
 
+    /// Calculate disk usage for images
+    /// - Parameter activeReferences: Set of image references currently in use by containers
+    /// - Returns: Tuple of (total count, active count, total size, reclaimable size)
+    public static func calculateDiskUsage(activeReferences: Set<String>) async throws -> (totalCount: Int, activeCount: Int, totalSize: UInt64, reclaimableSize: UInt64) {
+        let client = newXPCClient()
+        let request = newRequest(.imageDiskUsage)
+
+        // Encode active references
+        let activeRefsData = try JSONEncoder().encode(activeReferences)
+        request.set(key: .activeImageReferences, value: activeRefsData)
+
+        let response = try await client.send(request)
+        let total = Int(response.int64(key: .totalCount))
+        let active = Int(response.int64(key: .activeCount))
+        let size = response.uint64(key: .imageSize)
+        let reclaimable = response.uint64(key: .reclaimableSize)
+
+        return (totalCount: total, activeCount: active, totalSize: size, reclaimableSize: reclaimable)
+    }
+
     public static func fetch(reference: String, platform: Platform? = nil, scheme: RequestScheme = .auto, progressUpdate: ProgressUpdateHandler? = nil) async throws -> ClientImage
     {
         do {

Sources/ContainerClient/Core/ClientVolume.swift

@@ -91,7 +91,7 @@ public struct ClientVolume {
         }
 
         let volumeNames = try JSONDecoder().decode([String].self, from: responseData)
-        let size = reply.uint64(key: .size)
+        let size = reply.uint64(key: .volumeSize)
         return (volumeNames, size)
     }
 

Sources/ContainerClient/Core/DiskUsage.swift

@@ -0,0 +1,57 @@
+//===----------------------------------------------------------------------===//
+// 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 Foundation
+
+/// Disk usage statistics for all resource types
+public struct DiskUsageStats: Sendable, Codable {
+    /// Disk usage for images
+    public var images: ResourceUsage
+
+    /// Disk usage for containers
+    public var containers: ResourceUsage
+
+    /// Disk usage for volumes
+    public var volumes: ResourceUsage
+
+    public init(images: ResourceUsage, containers: ResourceUsage, volumes: ResourceUsage) {
+        self.images = images
+        self.containers = containers
+        self.volumes = volumes
+    }
+}
+
+/// Disk usage statistics for a specific resource type
+public struct ResourceUsage: Sendable, Codable {
+    /// Total number of resources
+    public var total: Int
+
+    /// Number of active/running resources
+    public var active: Int
+
+    /// Total size in bytes
+    public var sizeInBytes: UInt64
+
+    /// Reclaimable size in bytes (from unused/inactive resources)
+    public var reclaimable: UInt64
+
+    public init(total: Int, active: Int, sizeInBytes: UInt64, reclaimable: UInt64) {
+        self.total = total
+        self.active = active
+        self.sizeInBytes = sizeInBytes
+        self.reclaimable = reclaimable
+    }
+}

Sources/ContainerClient/Core/XPC+.swift

@@ -118,6 +118,10 @@ public enum XPCKeys: String {
 
     /// Container statistics
     case statistics
+    case volumeSize
+
+    /// Disk usage
+    case diskUsageStats
 }
 
 public enum XPCRoute: String {
@@ -153,6 +157,8 @@ public enum XPCRoute: String {
     case volumeInspect
     case volumePrune
 
+    case systemDiskUsage
+
     case ping
 
     case installKernel

Sources/ContainerCommands/System/SystemCommand.swift

@@ -23,6 +23,7 @@ extension Application {
             commandName: "system",
             abstract: "Manage system components",
             subcommands: [
+                SystemDF.self,
                 SystemDNS.self,
                 SystemKernel.self,
                 SystemLogs.self,

Sources/ContainerCommands/System/SystemDF.swift

@@ -0,0 +1,115 @@
+//===----------------------------------------------------------------------===//
+// 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 ContainerizationError
+import Foundation
+
+extension Application {
+    public struct SystemDF: AsyncParsableCommand {
+        public static let configuration = CommandConfiguration(
+            commandName: "df",
+            abstract: "Show disk usage for images, containers, and volumes"
+        )
+
+        @Option(name: .long, help: "Format of the output")
+        var format: ListFormat = .table
+
+        @OptionGroup
+        var global: Flags.Global
+
+        public init() {}
+
+        public func run() async throws {
+            let stats = try await ClientDiskUsage.get()
+
+            if format == .json {
+                let encoder = JSONEncoder()
+                encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+                let data = try encoder.encode(stats)
+                guard let jsonString = String(data: data, encoding: .utf8) else {
+                    throw ContainerizationError(
+                        .internalError,
+                        message: "Failed to encode JSON output"
+                    )
+                }
+                print(jsonString)
+                return
+            }
+
+            printTable(stats: stats)
+        }
+
+        private func printTable(stats: DiskUsageStats) {
+            var rows: [[String]] = []
+
+            // Header row
+            rows.append(["TYPE", "TOTAL", "ACTIVE", "SIZE", "RECLAIMABLE"])
+
+            // Images row
+            rows.append([
+                "Images",
+                "\(stats.images.total)",
+                "\(stats.images.active)",
+                formatSize(stats.images.sizeInBytes),
+                formatReclaimable(stats.images.reclaimable, total: stats.images.sizeInBytes),
+            ])
+
+            // Containers row
+            rows.append([
+                "Containers",
+                "\(stats.containers.total)",
+                "\(stats.containers.active)",
+                formatSize(stats.containers.sizeInBytes),
+                formatReclaimable(stats.containers.reclaimable, total: stats.containers.sizeInBytes),
+            ])
+
+            // Volumes row
+            rows.append([
+                "Local Volumes",
+                "\(stats.volumes.total)",
+                "\(stats.volumes.active)",
+                formatSize(stats.volumes.sizeInBytes),
+                formatReclaimable(stats.volumes.reclaimable, total: stats.volumes.sizeInBytes),
+            ])
+
+            let tableFormatter = TableOutput(rows: rows)
+            print(tableFormatter.format())
+        }
+
+        private func formatSize(_ bytes: UInt64) -> String {
+            if bytes == 0 {
+                return "0 B"
+            }
+            let formatter = ByteCountFormatter()
+            formatter.countStyle = .file
+            return formatter.string(fromByteCount: Int64(bytes))
+        }
+
+        private func formatReclaimable(_ reclaimable: UInt64, total: UInt64) -> String {
+            let sizeStr = formatSize(reclaimable)
+
+            if total == 0 {
+                return "\(sizeStr) (0%)"
+            }
+
+            // Cap at 100% in case reclaimable > total (shouldn't happen but be defensive)
+            let percentage = min(100, Int(round(Double(reclaimable) / Double(total) * 100.0)))
+            return "\(sizeStr) (\(percentage)%)"
+        }
+    }
+}

Sources/Helpers/APIServer/APIServer+Start.swift

@@ -67,7 +67,13 @@ extension APIServer {
                 )
                 initializeHealthCheckService(log: log, routes: &routes)
                 try initializeKernelService(log: log, routes: &routes)
-                try initializeVolumeService(containersService: containersService, log: log, routes: &routes)
+                let volumesService = try initializeVolumeService(containersService: containersService, log: log, routes: &routes)
+                try initializeDiskUsageService(
+                    containersService: containersService,
+                    volumesService: volumesService,
+                    log: log,
+                    routes: &routes
+                )
 
                 let server = XPCServer(
                     identifier: "com.apple.container.apiserver",
@@ -254,7 +260,7 @@ extension APIServer {
             containersService: ContainersService,
             log: Logger,
             routes: inout [XPCRoute: XPCServer.RouteHandler]
-        ) throws {
+        ) throws -> VolumesService {
             log.info("initializing volume service")
 
             let resourceRoot = appRoot.appendingPathComponent("volumes")
@@ -266,6 +272,26 @@ extension APIServer {
             routes[XPCRoute.volumeList] = harness.list
             routes[XPCRoute.volumeInspect] = harness.inspect
             routes[XPCRoute.volumePrune] = harness.prune
+
+            return service
+        }
+
+        private func initializeDiskUsageService(
+            containersService: ContainersService,
+            volumesService: VolumesService,
+            log: Logger,
+            routes: inout [XPCRoute: XPCServer.RouteHandler]
+        ) throws {
+            log.info("initializing disk usage service")
+
+            let service = DiskUsageService(
+                containersService: containersService,
+                volumesService: volumesService,
+                log: log
+            )
+            let harness = DiskUsageHarness(service: service, log: log)
+
+            routes[XPCRoute.systemDiskUsage] = harness.get
         }
     }
 }

Sources/Helpers/Images/ImagesHelper.swift

@@ -99,6 +99,7 @@ extension ImagesHelper {
             routes[ImagesServiceXPCRoute.imageLoad.rawValue] = harness.load
             routes[ImagesServiceXPCRoute.imageUnpack.rawValue] = harness.unpack
             routes[ImagesServiceXPCRoute.imagePrune.rawValue] = harness.prune
+            routes[ImagesServiceXPCRoute.imageDiskUsage.rawValue] = harness.calculateDiskUsage
             routes[ImagesServiceXPCRoute.snapshotDelete.rawValue] = harness.deleteSnapshot
             routes[ImagesServiceXPCRoute.snapshotGet.rawValue] = harness.getSnapshot
         }