fix(compose): fail fast on unusable and missing external volumes

Named volumes now reach the container as a bind mount, so a name that
cannot become a host path, or an external volume that was never created,
has to stop the project before anything starts instead of surfacing as a
raw path error once some services are already up. The check mirrors the
external-network one and runs before networks or volumes are created.

- reject volume names containing ':', which would misparse inside the
  -v source:destination argument
- resolveVolumeMounts takes the already-resolved backing directories
  instead of re-deriving them from the project name and volume store
- drop the hand-written changelog entry; release-please owns that file

Author: us

CHANGELOG.md

@@ -12,10 +12,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * **image inspect:** `mocker image inspect` and `mocker inspect --type=image` now return Docker-compatible `ImageInspect` JSON arrays with PascalCase keys instead of the previous lowercase `ImageInfo` object shape.
 * **MockerKit:** `ImageManager.inspect(_:platform:)` returns `ImageInspect` instead of `ImageInfo`.
 
-### Bug Fixes
-
-* **compose:** named volumes are now mounted into containers, so their data survives `compose up --force-recreate` instead of silently living in the container layer and being discarded. Volumes resolve to their backing directory under the volume store (`<volumesPath>/<runtimeName>/_data`), matching Docker's behaviour; `down --volumes` still removes them.
-
 ## [0.9.1](https://github.com/us/mocker/compare/v0.9.0...v0.9.1) (2026-08-09)
 
 

Sources/MockerKit/Compose/ComposeOrchestrator.swift

@@ -81,6 +81,21 @@ public actor ComposeOrchestrator {
             }
         }
 
+        // Named volumes are bind-mounted from their backing directory, so both an
+        // unusable name and a missing external volume have to fail here — before any
+        // service starts — rather than as a raw runtime path error half-way through.
+        if !composeFile.volumes.isEmpty {
+            let existing = Set(await volumeManager.list().map(\.name))
+            for volume in composeFile.volumes.values {
+                let name = volume.runtimeName(projectName: projectName)
+                _ = try volumeManager.mountpoint(name)
+                guard !volume.external || existing.contains(name) else {
+                    throw MockerError.operationFailed(
+                        "volume \(name) declared as external, but could not be found")
+                }
+            }
+        }
+
         // Create networks
         for (fullName, driver) in Self.networksToCreate(composeFile: composeFile, projectName: projectName) {
             do {
@@ -523,12 +538,14 @@ public actor ComposeOrchestrator {
         // Parse port mappings
         let ports = try service.ports.map { try PortMapping.parse($0) }
 
+        // Named volumes bind-mount their backing directory, exactly as Docker does
+        // internally, so the data survives container recreation.
         let volumes = try Self.resolveVolumeMounts(
             service.volumes,
             projectDir: projectDir,
-            projectName: projectName,
-            declaredVolumes: composeFile.volumes,
-            volumesPath: volumeManager.mountpointPath
+            namedVolumeSources: composeFile.volumes.mapValues {
+                try volumeManager.mountpoint($0.runtimeName(projectName: projectName))
+            }
         )
 
         let config = ContainerConfig(
@@ -569,13 +586,11 @@ public actor ComposeOrchestrator {
 
     /// Resolve volume spec strings from a compose service into `VolumeMount` values.
     ///
-    /// Bind-mount host paths (absolute, relative or `~`-anchored) and anonymous
-    /// volumes (container paths only) are included as-is. Named volumes are
-    /// resolved to their backing directory under `volumesPath`
-    /// (`<volumesPath>/<runtimeName>/_data`, where `runtimeName` applies the
-    /// project prefix unless the volume declares an explicit `name:` or is
-    /// `external:`), and bind-mounted — exactly what Docker does internally, and
-    /// what keeps the data alive across `compose up --force-recreate`.
+    /// Bind-mount host paths and anonymous volumes (container paths only) are
+    /// included as-is. A name declared in the file's top-level `volumes:` section is
+    /// bind-mounted from its backing directory (`namedVolumeSources`), which is what
+    /// keeps the data alive across `compose up --force-recreate`; an undeclared bare
+    /// name has no backing directory and is dropped.
     ///
     /// Relative paths (`./foo`, `../bar`, `data/dir`) are resolved to absolute paths
     /// against `projectDir` (the Compose `--project-directory`, i.e. the directory
@@ -585,37 +600,25 @@ public actor ComposeOrchestrator {
     static func resolveVolumeMounts(
         _ volSpecs: [String],
         projectDir: URL,
-        projectName: String,
-        declaredVolumes: [String: ComposeVolume],
-        volumesPath: String
+        namedVolumeSources: [String: String]
     ) throws -> [VolumeMount] {
         var volumes: [VolumeMount] = []
         for volSpec in volSpecs {
             var mount = try VolumeMount.parse(volSpec)
-            if mount.source.isEmpty {
-                // Anonymous volume: just a container path.
-                volumes.append(mount)
-            } else if mount.source.hasPrefix("/") {
-                // Absolute bind mount.
+            if mount.source.isEmpty || mount.source.hasPrefix("/") {
                 volumes.append(mount)
             } else if mount.source.hasPrefix("~") {
-                // Home-relative bind mount.
                 mount.source = (mount.source as NSString).expandingTildeInPath
                 volumes.append(mount)
             } else if mount.source.hasPrefix(".")
                       || mount.source.contains("/") {
                 // Relative bind mount, anchored to the project directory.
                 mount.source = projectDir.appendingPathComponent(mount.source).standardized.path
                 volumes.append(mount)
-            } else if let declared = declaredVolumes[mount.source] {
-                // Named volume: bind-mount the volume's backing directory so the
-                // data survives container recreation (issue #XX).
-                let runtimeName = declared.runtimeName(projectName: projectName)
-                mount.source = "\(volumesPath)/\(runtimeName)/_data"
+            } else if let source = namedVolumeSources[mount.source] {
+                mount.source = source
                 volumes.append(mount)
             }
-            // Anything else (e.g. an undeclared bare name) is silently dropped,
-            // matching the previous behaviour for non-declared names.
         }
         return volumes
     }

Sources/MockerKit/Volume/VolumeManager.swift

@@ -28,19 +28,23 @@ public actor VolumeManager {
         }
     }
 
-    /// Root directory where volume data lives (`<dataRoot>/volumes`). Every named
-    /// volume is stored under `<mountpointPath>/<name>/_data`, which is what compose
-    /// bind-mounts into containers so named volumes survive container recreation.
-    public nonisolated var mountpointPath: String { storagePath }
+    /// Backing directory holding a volume's data. Compose bind-mounts it so named
+    /// volumes survive container recreation.
+    public nonisolated func mountpoint(_ name: String) throws -> String {
+        try Self.validateName(name)
+        return "\(storagePath)/\(name)/_data"
+    }
 
     /// Reject names that would escape the volumes directory. Every volume path is
     /// built by interpolating the name, and a compose file can supply it verbatim
     /// (`volumes: {data: {name: ...}}`), so `../` must never get through.
     static func validateName(_ name: String) throws {
-        // Only path escape is rejected — anything else stays removable, including
-        // volumes created before this check existed.
+        // Path escape and `:` are rejected — the latter because the backing directory
+        // goes into a `-v source:destination` argument, where it would misparse.
+        // Anything else stays removable, including volumes created before this check.
         let valid = !name.isEmpty
             && !name.contains("/")
+            && !name.contains(":")
             && name != "."
             && name != ".."
         guard valid else {
@@ -50,12 +54,11 @@ public actor VolumeManager {
 
     /// Create a new volume.
     public func create(name: String, driver: String = "local", labels: [String: String] = [:]) throws -> VolumeInfo {
-        try Self.validateName(name)
         guard volumes[name] == nil else {
             throw MockerError.operationFailed("Volume \(name) already exists")
         }
 
-        let mountpoint = "\(config.volumesPath)/\(name)/_data"
+        let mountpoint = try mountpoint(name)
         let fm = FileManager.default
         if !fm.fileExists(atPath: mountpoint) {
             try fm.createDirectory(atPath: mountpoint, withIntermediateDirectories: true)

Tests/MockerKitTests/ComposeOrchestratorTests.swift

@@ -185,30 +185,12 @@ struct ComposeOrchestratorTests {
 
     @Test("Declared named volume resolved to its backing directory")
     func resolveDeclaredNamedVolume() throws {
-        let mounts = try Self.resolve(["mydata:/container/data"], declared: ["mydata"])
+        let mounts = try Self.resolve(["mydata:/container/data"], named: ["mydata": "/volumes/proj-mydata/_data"])
         #expect(mounts.count == 1)
         #expect(mounts[0].source == "/volumes/proj-mydata/_data")
         #expect(mounts[0].destination == "/container/data")
     }
 
-    @Test("Named volume with explicit name uses it verbatim")
-    func resolveNamedVolumeCustomName() throws {
-        let vol = ComposeVolume(name: "mydata", customName: "shared-data")
-        let mounts = try Self.resolve(["mydata:/container/data"], declaredVolumes: ["mydata": vol])
-        #expect(mounts.count == 1)
-        #expect(mounts[0].source == "/volumes/shared-data/_data")
-        #expect(mounts[0].destination == "/container/data")
-    }
-
-    @Test("External named volume keeps its declared key")
-    func resolveExternalNamedVolume() throws {
-        let vol = ComposeVolume(name: "mydata", external: true)
-        let mounts = try Self.resolve(["mydata:/container/data"], declaredVolumes: ["mydata": vol])
-        #expect(mounts.count == 1)
-        #expect(mounts[0].source == "/volumes/mydata/_data")
-        #expect(mounts[0].destination == "/container/data")
-    }
-
     @Test("Undeclared bare name is dropped")
     func dropUndeclaredName() throws {
         let mounts = try Self.resolve(["mydata:/container/data"])
@@ -231,7 +213,7 @@ struct ComposeOrchestratorTests {
             "namedvol:/app/named",
             "/app/anon",
             "sub/dir:/app/sub",
-        ], declared: ["namedvol"])
+        ], named: ["namedvol": "/volumes/proj-namedvol/_data"])
         #expect(mounts.count == 5)
         let sources = mounts.map(\.source)
         #expect(sources.contains("/abs/path"))
@@ -259,29 +241,16 @@ struct ComposeOrchestratorTests {
         #expect(mounts[0].destination == "/container/data")
     }
 
-    /// Convenience wrapper: resolve specs with a fixed project name/volumes path
-    /// and no declared volumes.
+    /// Resolve specs against the test project directory, with named volumes already
+    /// mapped to their backing directories.
     private static func resolve(
         _ specs: [String],
-        declared declaredKeys: [String] = []
-    ) throws -> [VolumeMount] {
-        let declared = Dictionary(uniqueKeysWithValues: declaredKeys.map {
-            ($0, ComposeVolume(name: $0))
-        })
-        return try resolve(specs, declaredVolumes: declared)
-    }
-
-    /// Convenience wrapper with an explicit volume declaration map.
-    private static func resolve(
-        _ specs: [String],
-        declaredVolumes: [String: ComposeVolume]
+        named: [String: String] = [:]
     ) throws -> [VolumeMount] {
         try ComposeOrchestrator.resolveVolumeMounts(
             specs,
             projectDir: Self.cwd,
-            projectName: "proj",
-            declaredVolumes: declaredVolumes,
-            volumesPath: "/volumes"
+            namedVolumeSources: named
         )
     }
 
@@ -542,9 +511,7 @@ struct ComposeOrchestratorTests {
         let mounts = try ComposeOrchestrator.resolveVolumeMounts(
             ["./data:/container/data"],
             projectDir: projectDir,
-            projectName: "proj",
-            declaredVolumes: [:],
-            volumesPath: "/volumes"
+            namedVolumeSources: [:]
         )
         #expect(mounts.count == 1)
         #expect(mounts[0].source == "/tmp/mocker-issue-60-project/data")
@@ -557,9 +524,7 @@ struct ComposeOrchestratorTests {
         let mounts = try ComposeOrchestrator.resolveVolumeMounts(
             ["../shared:/container/shared"],
             projectDir: projectDir,
-            projectName: "proj",
-            declaredVolumes: [:],
-            volumesPath: "/volumes"
+            namedVolumeSources: [:]
         )
         #expect(mounts.count == 1)
         #expect(mounts[0].source == "/tmp/mocker-issue-60-project/shared")

Tests/MockerKitTests/ComposeVolumeLifecycleTests.swift

@@ -94,7 +94,7 @@ struct ComposeVolumeLifecycleTests {
     }
 
     @Test("Volume names that would escape the volumes directory are rejected", arguments: [
-        "../etc", "a/b", "..", ".", "",
+        "../etc", "a/b", "..", ".", "", "host:path",
     ])
     func rejectsEscapingVolumeNames(name: String) {
         #expect(throws: MockerError.self) {