add volume prune command

Sources/ContainerClient/Core/ClientVolume.swift

@@ -81,4 +81,18 @@ public struct ClientVolume {
         return try JSONDecoder().decode(Volume.self, from: responseData)
     }
 
+    public static func prune() async throws -> ([String], UInt64) {
+        let client = XPCClient(service: serviceIdentifier)
+        let message = XPCMessage(route: .volumePrune)
+        let reply = try await client.send(message)
+
+        guard let responseData = reply.dataNoCopy(key: .volumes) else {
+            return ([], 0)
+        }
+
+        let volumeNames = try JSONDecoder().decode([String].self, from: responseData)
+        let size = reply.uint64(key: .size)
+        return (volumeNames, size)
+    }
+
 }

Sources/ContainerClient/Core/XPC+.swift

@@ -147,6 +147,7 @@ public enum XPCRoute: String {
     case volumeDelete
     case volumeList
     case volumeInspect
+    case volumePrune
 
     case ping
 

Sources/ContainerCommands/Volume/VolumeCommand.swift

@@ -26,6 +26,7 @@ extension Application {
                 VolumeDelete.self,
                 VolumeList.self,
                 VolumeInspect.self,
+                VolumePrune.self,
             ],
             aliases: ["v"]
         )

Sources/ContainerCommands/Volume/VolumePrune.swift

@@ -0,0 +1,48 @@
+//===----------------------------------------------------------------------===//
+// 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 Foundation
+
+extension Application.VolumeCommand {
+    public struct VolumePrune: AsyncParsableCommand {
+        public init() {}
+        public static let configuration = CommandConfiguration(
+            commandName: "prune",
+            abstract: "Remove volumes with no container references")
+
+        @OptionGroup
+        var global: Flags.Global
+
+        public func run() async throws {
+            let (volumeNames, size) = try await ClientVolume.prune()
+            let formatter = ByteCountFormatter()
+            let freed = formatter.string(fromByteCount: Int64(size))
+
+            if volumeNames.isEmpty {
+                print("No volumes to prune")
+            } else {
+                print("Pruned volumes:")
+                for name in volumeNames {
+                    print(name)
+                }
+                print()
+            }
+            print("Reclaimed \(freed) in disk space")
+        }
+    }
+}

Sources/Helpers/APIServer/APIServer+Start.swift

@@ -264,6 +264,7 @@ extension APIServer {
             routes[XPCRoute.volumeDelete] = harness.delete
             routes[XPCRoute.volumeList] = harness.list
             routes[XPCRoute.volumeInspect] = harness.inspect
+            routes[XPCRoute.volumePrune] = harness.prune
         }
     }
 }

Sources/Services/ContainerAPIService/Volumes/VolumesHarness.swift

@@ -92,4 +92,15 @@ public struct VolumesHarness: Sendable {
         reply.set(key: .volume, value: data)
         return reply
     }
+
+    @Sendable
+    public func prune(_ message: XPCMessage) async throws -> XPCMessage {
+        let (volumeNames, size) = try await service.prune()
+        let data = try JSONEncoder().encode(volumeNames)
+
+        let reply = message.reply()
+        reply.set(key: .volumes, value: data)
+        reply.set(key: .size, value: size)
+        return reply
+    }
 }

Sources/Services/ContainerAPIService/Volumes/VolumesService.swift

@@ -72,6 +72,77 @@ public actor VolumesService {
         }
     }
 
+    public func prune() async throws -> ([String], UInt64) {
+        try await lock.withLock { _ in
+            let allVolumes = try await self.store.list()
+
+            // do entire prune operation atomically with container list
+            return try await self.containersService.withContainerList { containers in
+                var inUseSet = Set<String>()
+                for container in containers {
+                    for mount in container.configuration.mounts {
+                        if mount.isVolume, let volumeName = mount.volumeName {
+                            inUseSet.insert(volumeName)
+                        }
+                    }
+                }
+
+                let volumesToPrune = allVolumes.filter { volume in
+                    !inUseSet.contains(volume.name)
+                }
+
+                var prunedNames = [String]()
+                var totalSize: UInt64 = 0
+
+                for volume in volumesToPrune {
+                    do {
+                        // calculate actual disk usage before deletion
+                        let volumePath = self.volumePath(for: volume.name)
+                        let actualSize = self.calculateDirectorySize(at: volumePath)
+
+                        try await self.store.delete(volume.name)
+                        try self.removeVolumeDirectory(for: volume.name)
+
+                        prunedNames.append(volume.name)
+                        totalSize += actualSize
+                        self.log.info("Pruned volume", metadata: ["name": "\(volume.name)", "size": "\(actualSize)"])
+                    } catch {
+                        self.log.error("Failed to prune volume \(volume.name): \(error)")
+                    }
+                }
+
+                return (prunedNames, totalSize)
+            }
+        }
+    }
+
+    private nonisolated func calculateDirectorySize(at path: String) -> UInt64 {
+        let url = URL(fileURLWithPath: path)
+        let fileManager = FileManager.default
+
+        guard
+            let enumerator = fileManager.enumerator(
+                at: url,
+                includingPropertiesForKeys: [.totalFileAllocatedSizeKey],
+                options: [.skipsHiddenFiles]
+            )
+        else {
+            return 0
+        }
+
+        var totalSize: UInt64 = 0
+        for case let fileURL as URL in enumerator {
+            guard let resourceValues = try? fileURL.resourceValues(forKeys: [.totalFileAllocatedSizeKey]),
+                let fileSize = resourceValues.totalFileAllocatedSize
+            else {
+                continue
+            }
+            totalSize += UInt64(fileSize)
+        }
+
+        return totalSize
+    }
+
     private func parseSize(_ sizeString: String) throws -> UInt64 {
         let measurement = try Measurement.parse(parsing: sizeString)
         let bytes = measurement.converted(to: .bytes).value
@@ -162,7 +233,8 @@ public actor VolumesService {
             format: "ext4",
             source: blockPath(for: name),
             labels: labels,
-            options: driverOpts
+            options: driverOpts,
+            sizeInBytes: sizeInBytes
         )
 
         try await store.create(volume)

Tests/CLITests/Subcommands/Volumes/TestCLIVolumes.swift

@@ -18,6 +18,7 @@ import ContainerClient
 import Foundation
 import Testing
 
+@Suite(.serialized)
 class TestCLIVolumes: CLITest {
 
     func doVolumeCreate(name: String) throws {
@@ -323,4 +324,132 @@ class TestCLIVolumes: CLITest {
 
         #expect(status2 == 0, "second container should succeed")
     }
+
+    @Test func testVolumePruneNoVolumes() throws {
+        // Prune with no volumes should succeed with 0 reclaimed
+        let (output, error, status) = try run(arguments: ["volume", "prune"])
+        if status != 0 {
+            throw CLIError.executionFailed("volume prune failed: \(error)")
+        }
+
+        #expect(output.contains("0 B") || output.contains("No volumes to prune"), "should show no space reclaimed or no volumes message")
+    }
+
+    @Test func testVolumePruneUnusedVolumes() throws {
+        let testName = getTestName()
+        let volumeName1 = "\(testName)_vol1"
+        let volumeName2 = "\(testName)_vol2"
+
+        // Clean up any existing resources from previous runs
+        doVolumeDeleteIfExists(name: volumeName1)
+        doVolumeDeleteIfExists(name: volumeName2)
+
+        defer {
+            doVolumeDeleteIfExists(name: volumeName1)
+            doVolumeDeleteIfExists(name: volumeName2)
+        }
+
+        try doVolumeCreate(name: volumeName1)
+        try doVolumeCreate(name: volumeName2)
+        let (listBefore, _, statusBefore) = try run(arguments: ["volume", "list", "--quiet"])
+        #expect(statusBefore == 0)
+        #expect(listBefore.contains(volumeName1))
+        #expect(listBefore.contains(volumeName2))
+
+        // Prune should remove both
+        let (output, error, status) = try run(arguments: ["volume", "prune"])
+        if status != 0 {
+            throw CLIError.executionFailed("volume prune failed: \(error)")
+        }
+
+        #expect(output.contains(volumeName1) || !output.contains("No volumes to prune"), "should prune volume1")
+        #expect(output.contains(volumeName2) || !output.contains("No volumes to prune"), "should prune volume2")
+        #expect(output.contains("Reclaimed"), "should show reclaimed space")
+
+        // Verify volumes are gone
+        let (listAfter, _, statusAfter) = try run(arguments: ["volume", "list", "--quiet"])
+        #expect(statusAfter == 0)
+        #expect(!listAfter.contains(volumeName1), "volume1 should be pruned")
+        #expect(!listAfter.contains(volumeName2), "volume2 should be pruned")
+    }
+
+    @Test func testVolumePruneSkipsVolumeInUse() throws {
+        let testName = getTestName()
+        let volumeInUse = "\(testName)_inuse"
+        let volumeUnused = "\(testName)_unused"
+        let containerName = "\(testName)_c1"
+
+        // Clean up any existing resources from previous runs
+        doVolumeDeleteIfExists(name: volumeInUse)
+        doVolumeDeleteIfExists(name: volumeUnused)
+        doRemoveIfExists(name: containerName, force: true)
+
+        defer {
+            try? doStop(name: containerName)
+            doRemoveIfExists(name: containerName, force: true)
+            doVolumeDeleteIfExists(name: volumeInUse)
+            doVolumeDeleteIfExists(name: volumeUnused)
+        }
+
+        try doVolumeCreate(name: volumeInUse)
+        try doVolumeCreate(name: volumeUnused)
+        try doLongRun(name: containerName, args: ["-v", "\(volumeInUse):/data"])
+        try waitForContainerRunning(containerName)
+
+        // Prune should only remove the unused volume
+        let (_, error, status) = try run(arguments: ["volume", "prune"])
+        if status != 0 {
+            throw CLIError.executionFailed("volume prune failed: \(error)")
+        }
+
+        // Verify in-use volume still exists
+        let (listAfter, _, statusAfter) = try run(arguments: ["volume", "list", "--quiet"])
+        #expect(statusAfter == 0)
+        #expect(listAfter.contains(volumeInUse), "volume in use should NOT be pruned")
+        #expect(!listAfter.contains(volumeUnused), "unused volume should be pruned")
+
+        try doStop(name: containerName)
+        doRemoveIfExists(name: containerName, force: true)
+        doVolumeDeleteIfExists(name: volumeInUse)
+    }
+
+    @Test func testVolumePruneSkipsVolumeAttachedToStoppedContainer() async throws {
+        let testName = getTestName()
+        let volumeName = "\(testName)_vol"
+        let containerName = "\(testName)_c1"
+
+        // Clean up any existing resources from previous runs
+        doVolumeDeleteIfExists(name: volumeName)
+        doRemoveIfExists(name: containerName, force: true)
+
+        defer {
+            doRemoveIfExists(name: containerName, force: true)
+            doVolumeDeleteIfExists(name: volumeName)
+        }
+
+        try doVolumeCreate(name: volumeName)
+        try doCreate(name: containerName, image: alpine, volumes: ["\(volumeName):/data"])
+        try await Task.sleep(for: .seconds(1))
+
+        // Prune should NOT remove the volume (container exists, even if stopped)
+        let (_, error, status) = try run(arguments: ["volume", "prune"])
+        if status != 0 {
+            throw CLIError.executionFailed("volume prune failed: \(error)")
+        }
+
+        let (listAfter, _, statusAfter) = try run(arguments: ["volume", "list", "--quiet"])
+        #expect(statusAfter == 0)
+        #expect(listAfter.contains(volumeName), "volume attached to stopped container should NOT be pruned")
+
+        doRemoveIfExists(name: containerName, force: true)
+        let (_, error2, status2) = try run(arguments: ["volume", "prune"])
+        if status2 != 0 {
+            throw CLIError.executionFailed("volume prune failed: \(error2)")
+        }
+
+        // Verify volume is gone
+        let (listFinal, _, statusFinal) = try run(arguments: ["volume", "list", "--quiet"])
+        #expect(statusFinal == 0)
+        #expect(!listFinal.contains(volumeName), "volume should be pruned after container is deleted")
+    }
 }