add volume prune command (#783)

- Closes #508.

## Type of Change
- [ ] Bug fix
- [x] New feature  
- [ ] Breaking change
- [ ] Documentation update

## Motivation and Context
Adds a `container volume prune` command that removes volumes with no
container references and reports the amount of disk space reclaimed.
This helps users clean up unused volumes and easily reclaim disk space.

Also updates the `volume delete` documentation to clarify and highlight
how the `--all` flag works.

## Testing
- [x] Tested locally
- [x] Added/updated tests
- [x] Added/updated docs

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")
+    }
 }

docs/command-reference.md

@@ -617,15 +617,66 @@ container volume rm $VOL
 
 ### `container volume delete (rm)`
 
-Removes one or more volumes by name.
+Removes one or more volumes by name. Volumes that are currently in use by containers (running or stopped) cannot be deleted.
 
 **Usage**
 
 ```bash
-container volume delete NAME...
+container volume delete [OPTIONS] [NAME...]
 ```
 
-Only global flags are available.
+**Arguments**
+
+*   `NAME...`: Volume names to delete
+
+**Options**
+
+*   `-a, --all`: Delete all volumes (only removes volumes not in use)
+*   **Global**: `--debug`, `--version`, `-h`/`--help`
+
+**Examples**
+
+```bash
+# delete a specific volume
+container volume delete myvolume
+
+# delete multiple volumes
+container volume delete vol1 vol2 vol3
+
+# delete all unused volumes
+container volume delete --all
+```
+
+### `container volume prune`
+
+Removes all volumes that have no container references. This includes volumes that are not attached to any running or stopped containers. The command reports the actual disk space reclaimed after deletion.
+
+**Usage**
+
+```bash
+container volume prune [OPTIONS]
+```
+
+**Options**
+
+*   **Global**: `--debug`, `--version`, `-h`/`--help`
+
+**Examples**
+
+```bash
+# remove all unused volumes
+container volume prune
+```
+
+**Example output:**
+
+```
+Pruned volumes:
+vol1
+vol2
+
+Reclaimed 71.8 MB in disk space
+```
 
 ### `container volume list (ls)`