Replace SystemRuntimeOptions with PathUtils + ConfigurationLoader

noah-thor · noah-thor · commit 9da397530776 · 2026-05-06T11:01:20.000-07:00
Separates path resolution (PathUtils) from TOML loading
(ConfigurationLoader) in ContainerPersistence.

- PathUtils: resolves base paths for .home (XDG priority) and .appRoot
- ConfigurationLoader: load() reads from appRoot, copyConfigToAppRoot()
  syncs user config with non-throwing error logging
- ContainerSystemConfig: now non-final with Initable conformance
- All ~17 callsites simplified to ConfigurationLoader.load()
diff --git a/Sources/APIServer/APIServer+Start.swift b/Sources/APIServer/APIServer+Start.swift
@@ -50,9 +50,7 @@ extension APIServer {
         var logRoot = LogRoot.path
 
         func run() async throws {
-            let containerSystemConfig: ContainerSystemConfig = try SystemRuntimeOptions.loadConfig(
-                configFile: SystemRuntimeOptions.configFileFromAppRoot(ApplicationRoot.url)
-            )
+            let containerSystemConfig: ContainerSystemConfig = try ConfigurationLoader.load()
             let commandName = APIServer._commandName
             let logPath = logRoot.map { $0.appending("\(commandName).log") }
             let log = ServiceLogger.bootstrap(category: "APIServer", debug: debug, logPath: logPath)
diff --git a/Sources/ContainerCommands/BuildCommand.swift b/Sources/ContainerCommands/BuildCommand.swift
@@ -149,9 +149,7 @@ extension Application {
         var pull: Bool = false
 
         public func run() async throws {
-            let containerSystemConfig: ContainerSystemConfig = try SystemRuntimeOptions.loadConfig(
-                configFile: SystemRuntimeOptions.configFileFromAppRoot(ApplicationRoot.url)
-            )
+            let containerSystemConfig: ContainerSystemConfig = try ConfigurationLoader.load()
             do {
                 let timeout: Duration = .seconds(300)
                 let progressConfig = try ProgressConfig(
diff --git a/Sources/ContainerCommands/Builder/BuilderStart.swift b/Sources/ContainerCommands/Builder/BuilderStart.swift
@@ -55,9 +55,7 @@ extension Application {
         public init() {}
 
         public func run() async throws {
-            let containerSystemConfig: ContainerSystemConfig = try SystemRuntimeOptions.loadConfig(
-                configFile: SystemRuntimeOptions.configFileFromAppRoot(ApplicationRoot.url)
-            )
+            let containerSystemConfig: ContainerSystemConfig = try ConfigurationLoader.load()
             let progressConfig = try ProgressConfig(
                 showTasks: true,
                 showItems: true,
diff --git a/Sources/ContainerCommands/Container/ContainerCreate.swift b/Sources/ContainerCommands/Container/ContainerCreate.swift
@@ -56,9 +56,7 @@ extension Application {
         var arguments: [String] = []
 
         public func run() async throws {
-            let containerSystemConfig: ContainerSystemConfig = try SystemRuntimeOptions.loadConfig(
-                configFile: SystemRuntimeOptions.configFileFromAppRoot(ApplicationRoot.url)
-            )
+            let containerSystemConfig: ContainerSystemConfig = try ConfigurationLoader.load()
             let progressConfig = try ProgressConfig(
                 showTasks: true,
                 showItems: true,
diff --git a/Sources/ContainerCommands/Container/ContainerRun.swift b/Sources/ContainerCommands/Container/ContainerRun.swift
@@ -63,9 +63,7 @@ extension Application {
         var arguments: [String] = []
 
         public func run() async throws {
-            let containerSystemConfig: ContainerSystemConfig = try SystemRuntimeOptions.loadConfig(
-                configFile: SystemRuntimeOptions.configFileFromAppRoot(ApplicationRoot.url)
-            )
+            let containerSystemConfig: ContainerSystemConfig = try ConfigurationLoader.load()
             var exitCode: Int32 = 127
             let id = Utility.createContainerID(name: self.managementFlags.name)
 
diff --git a/Sources/ContainerCommands/Image/ImageDelete.swift b/Sources/ContainerCommands/Image/ImageDelete.swift
@@ -109,9 +109,7 @@ extension Application {
         }
 
         public mutating func run() async throws {
-            let containerSystemConfig: ContainerSystemConfig = try SystemRuntimeOptions.loadConfig(
-                configFile: SystemRuntimeOptions.configFileFromAppRoot(ApplicationRoot.url)
-            )
+            let containerSystemConfig: ContainerSystemConfig = try ConfigurationLoader.load()
             try await DeleteImageImplementation.removeImage(options: options, containerSystemConfig: containerSystemConfig, log: log)
         }
     }
diff --git a/Sources/ContainerCommands/Image/ImageInspect.swift b/Sources/ContainerCommands/Image/ImageInspect.swift
@@ -45,9 +45,7 @@ extension Application {
         }
 
         public func run() async throws {
-            let containerSystemConfig: ContainerSystemConfig = try SystemRuntimeOptions.loadConfig(
-                configFile: SystemRuntimeOptions.configFileFromAppRoot(ApplicationRoot.url)
-            )
+            let containerSystemConfig: ContainerSystemConfig = try ConfigurationLoader.load()
             var printable: [ImageDetail] = []
             var succeededImages: [String] = []
             var allErrors: [(String, Error)] = []
diff --git a/Sources/ContainerCommands/Image/ImageList.swift b/Sources/ContainerCommands/Image/ImageList.swift
@@ -45,9 +45,7 @@ extension Application {
         public var logOptions: Flags.Logging
 
         public mutating func run() async throws {
-            let containerSystemConfig: ContainerSystemConfig = try SystemRuntimeOptions.loadConfig(
-                configFile: SystemRuntimeOptions.configFileFromAppRoot(ApplicationRoot.url)
-            )
+            let containerSystemConfig: ContainerSystemConfig = try ConfigurationLoader.load()
             try Self.validate(format: format, quiet: quiet, verbose: verbose)
 
             var images = try await ClientImage.list().filter { img in
diff --git a/Sources/ContainerCommands/Image/ImagePull.swift b/Sources/ContainerCommands/Image/ImagePull.swift
@@ -69,9 +69,7 @@ extension Application {
         }
 
         public func run() async throws {
-            let containerSystemConfig: ContainerSystemConfig = try SystemRuntimeOptions.loadConfig(
-                configFile: SystemRuntimeOptions.configFileFromAppRoot(ApplicationRoot.url)
-            )
+            let containerSystemConfig: ContainerSystemConfig = try ConfigurationLoader.load()
             let p = try DefaultPlatform.resolve(platform: platform, os: os, arch: arch, log: log)
 
             let scheme = try RequestScheme(registry.scheme)
diff --git a/Sources/ContainerCommands/Image/ImagePush.swift b/Sources/ContainerCommands/Image/ImagePush.swift
@@ -57,9 +57,7 @@ extension Application {
         public init() {}
 
         public func run() async throws {
-            let containerSystemConfig: ContainerSystemConfig = try SystemRuntimeOptions.loadConfig(
-                configFile: SystemRuntimeOptions.configFileFromAppRoot(ApplicationRoot.url)
-            )
+            let containerSystemConfig: ContainerSystemConfig = try ConfigurationLoader.load()
             let p = try DefaultPlatform.resolve(platform: platform, os: os, arch: arch, log: log)
 
             let scheme = try RequestScheme(registry.scheme)
diff --git a/Sources/ContainerCommands/Image/ImageSave.swift b/Sources/ContainerCommands/Image/ImageSave.swift
@@ -62,9 +62,7 @@ extension Application {
         @Argument var references: [String]
 
         public func run() async throws {
-            let containerSystemConfig: ContainerSystemConfig = try SystemRuntimeOptions.loadConfig(
-                configFile: SystemRuntimeOptions.configFileFromAppRoot(ApplicationRoot.url)
-            )
+            let containerSystemConfig: ContainerSystemConfig = try ConfigurationLoader.load()
             let p = try DefaultPlatform.resolve(platform: platform, os: os, arch: arch, log: log)
 
             let progressConfig = try ProgressConfig(
diff --git a/Sources/ContainerCommands/Image/ImageTag.swift b/Sources/ContainerCommands/Image/ImageTag.swift
@@ -36,9 +36,7 @@ extension Application {
         public var logOptions: Flags.Logging
 
         public func run() async throws {
-            let containerSystemConfig: ContainerSystemConfig = try SystemRuntimeOptions.loadConfig(
-                configFile: SystemRuntimeOptions.configFileFromAppRoot(ApplicationRoot.url)
-            )
+            let containerSystemConfig: ContainerSystemConfig = try ConfigurationLoader.load()
             let existing = try await ClientImage.get(reference: source, containerSystemConfig: containerSystemConfig)
             let targetReference = try ClientImage.normalizeReference(target, containerSystemConfig: containerSystemConfig)
             try await existing.tag(new: targetReference)
diff --git a/Sources/ContainerCommands/Registry/RegistryLogin.swift b/Sources/ContainerCommands/Registry/RegistryLogin.swift
@@ -47,9 +47,7 @@ extension Application {
         var server: String
 
         public func run() async throws {
-            let containerSystemConfig: ContainerSystemConfig = try SystemRuntimeOptions.loadConfig(
-                configFile: SystemRuntimeOptions.configFileFromAppRoot(ApplicationRoot.url)
-            )
+            let containerSystemConfig: ContainerSystemConfig = try ConfigurationLoader.load()
             var username = self.username
             var password = ""
             if passwordStdin {
diff --git a/Sources/ContainerCommands/System/Kernel/KernelSet.swift b/Sources/ContainerCommands/System/Kernel/KernelSet.swift
@@ -53,9 +53,7 @@ extension Application {
         public init() {}
 
         public func run() async throws {
-            let containerSystemConfig: ContainerSystemConfig = try SystemRuntimeOptions.loadConfig(
-                configFile: SystemRuntimeOptions.configFileFromAppRoot(ApplicationRoot.url)
-            )
+            let containerSystemConfig: ContainerSystemConfig = try ConfigurationLoader.load()
             if recommended {
                 let url = containerSystemConfig.kernel.url
                 let path: String = containerSystemConfig.kernel.binaryPath
diff --git a/Sources/ContainerCommands/System/Property/PropertyList.swift b/Sources/ContainerCommands/System/Property/PropertyList.swift
@@ -42,9 +42,7 @@ extension Application {
         public init() {}
 
         public func run() async throws {
-            let containerSystemConfig: ContainerSystemConfig = try SystemRuntimeOptions.loadConfig(
-                configFile: SystemRuntimeOptions.configFileFromAppRoot(ApplicationRoot.url)
-            )
+            let containerSystemConfig: ContainerSystemConfig = try ConfigurationLoader.load()
             let output =
                 switch format {
                 case .json: try Output.renderJSON(containerSystemConfig)
diff --git a/Sources/ContainerCommands/System/SystemStart.swift b/Sources/ContainerCommands/System/SystemStart.swift
@@ -72,12 +72,8 @@ extension Application {
         public init() {}
 
         public func run() async throws {
-            let containerSystemConfig: ContainerSystemConfig = try SystemRuntimeOptions.loadConfig(
-                configFile: SystemRuntimeOptions.configFileFromAppRoot(ApplicationRoot.url)
-            )
-            // Copy the user's config into appRoot/config/ so that all plugins
-            // and the apiserver subsequently read the same snapshot.
-            SystemRuntimeOptions.copyConfigToAppRoot(appRoot: appRoot)
+            ConfigurationLoader.copyConfigToAppRoot()
+            let containerSystemConfig: ContainerSystemConfig = try ConfigurationLoader.load()
 
             // Without the true path to the binary in the plist, `container-apiserver` won't launch properly.
             // Resolve the symlink to get the true binary path before writing the launchd plist.
diff --git a/Sources/ContainerPersistence/ConfigurationLoader.swift b/Sources/ContainerPersistence/ConfigurationLoader.swift
@@ -16,66 +16,78 @@
 
 import ContainerizationError
 import Foundation
+import Logging
 import SystemPackage
 import TOML
 
+public protocol Initable {
+    init()
+}
+
+private let log = Logger(label: "ConfigurationLoader")
+
 public enum ConfigurationLoader {
-    public static func load<T: Codable & Sendable>(configFile: FilePath) throws -> T {
-        let path = configFile.string
-        guard FileManager.default.fileExists(atPath: path) else {
-            do {
-                return try TOMLDecoder().decode(T.self, from: Data("".utf8))
-            } catch {
-                throw ContainerizationError(.internalError, message: "failed to initialize default configuration: \(error)")
-            }
+    private static let configFilename = "runtime-config.toml"
+
+    public static func load<T: Codable & Sendable & Initable>() throws -> T {
+        let path = PathUtils.BaseConfigPath.appRoot.basePath()
+            .appending("config")
+            .appending(configFilename)
+        return try load(configFile: path)
+    }
+
+    static func load<T: Codable & Sendable & Initable>(configFile: FilePath) throws -> T {
+        guard FileManager.default.fileExists(atPath: configFile.string) else {
+            return T()
         }
         do {
-            let data = try Data(contentsOf: URL(fileURLWithPath: path))
+            let data = try Data(contentsOf: URL(filePath: configFile.string))
             return try TOMLDecoder().decode(T.self, from: data)
         } catch {
-            throw ContainerizationError(.invalidArgument, message: "failed to load configuration from '\(path)': \(error)")
+            throw ContainerizationError(
+                .invalidArgument,
+                message: "failed to load configuration from '\(configFile)': \(error)"
+            )
         }
     }
 
-    public static func copyConfigToAppRoot(
-        appRoot: URL,
-        userConfigPath: FilePath? = nil
-    ) throws {
-        let fm = FileManager.default
-        let source: FilePath
-        if let provided = userConfigPath {
-            source = provided
-            guard fm.fileExists(atPath: source.string) else {
-                throw ContainerizationError(
-                    .invalidArgument,
-                    message: "user config file not found at '\(source.string)'"
-                )
-            }
-        } else {
-            guard let resolved = UserConfiguration.resolve(from: .home, relativePath: "config.toml") else {
-                return
-            }
-            source = resolved
+    public static func copyConfigToAppRoot() throws {
+        let source = PathUtils.BaseConfigPath.home.basePath()
+            .appending(configFilename)
+        let destination = PathUtils.BaseConfigPath.appRoot.basePath()
+            .appending("config")
+            .appending(configFilename)
+        do {
+            try copyConfigToAppRoot(from: source, to: destination)
+        } catch {
+            throw ContainerizationError(
+            .invalidState, message: "Failed to copy user TOML to AppRoot `\(error)`")
         }
+    }
 
-        let configDir = appRoot.appendingPathComponent("config")
-        let destPath = configDir.appendingPathComponent("config.toml")
-        do {
-            try fm.createDirectory(at: configDir, withIntermediateDirectories: true)
-            if fm.fileExists(atPath: destPath.path(percentEncoded: false)) {
-                try fm.setAttributes([.posixPermissions: 0o644], ofItemAtPath: destPath.path(percentEncoded: false))
-                try fm.removeItem(at: destPath)
+    static func copyConfigToAppRoot(from source: FilePath, to destination: FilePath) throws {
+        let fm = FileManager.default
+        guard fm.fileExists(atPath: source.string) else { return }
+
+            let destDir = destination.removingLastComponent()
+            try fm.createDirectory(
+                atPath: destDir.string,
+                withIntermediateDirectories: true
+            )
+            if fm.fileExists(atPath: destination.string) {
+                try fm.setAttributes(
+                    [.posixPermissions: 0o644],
+                    ofItemAtPath: destination.string
+                )
+                try fm.removeItem(at: URL(filePath: destination.string))
             }
             try fm.copyItem(
-                at: URL(fileURLWithPath: source.string),
-                to: destPath
+                at: URL(filePath: source.string),
+                to: URL(filePath: destination.string)
             )
             try fm.setAttributes(
                 [.posixPermissions: 0o444],
-                ofItemAtPath: destPath.path(percentEncoded: false)
+                ofItemAtPath: destination.string
             )
-        } catch {
-            throw ContainerizationError(.internalError, message: "failed to copy runtime config to app root: \(error)")
-        }
     }
 }
diff --git a/Sources/ContainerPersistence/ContainerSystemConfig.swift b/Sources/ContainerPersistence/ContainerSystemConfig.swift
@@ -23,7 +23,7 @@ import Foundation
 ///
 /// Each section maps to a nested struct. Missing keys fall back to
 /// hardcoded defaults via custom `init(from:)` implementations.
-final public class ContainerSystemConfig: Codable, Sendable {
+public class ContainerSystemConfig: Codable, @unchecked Sendable, Initable {
     public let build: BuildConfig
     public let container: ContainerConfig
     public let dns: DNSConfig
@@ -50,7 +50,17 @@ final public class ContainerSystemConfig: Codable, Sendable {
         self.vminit = vminit
     }
 
-    public init(from decoder: any Decoder) throws {
+    required public init() {
+        self.build = .init()
+        self.container = .init()
+        self.dns = .init()
+        self.kernel = .init()
+        self.network = .init()
+        self.registry = .init()
+        self.vminit = .init()
+    }
+
+    required public init(from decoder: any Decoder) throws {
         let container = try decoder.container(keyedBy: CodingKeys.self)
         self.build = try container.decodeIfPresent(BuildConfig.self, forKey: .build) ?? .init()
         self.container = try container.decodeIfPresent(ContainerConfig.self, forKey: .container) ?? .init()
diff --git a/Sources/ContainerPersistence/PathUtils.swift b/Sources/ContainerPersistence/PathUtils.swift
@@ -0,0 +1,47 @@
+//===----------------------------------------------------------------------===//
+// Copyright © 2026 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
+import SystemPackage
+
+public enum PathUtils {
+    public enum BaseConfigPath {
+        case home
+        case appRoot
+
+        public func basePath() -> FilePath {
+            switch self {
+            case .home:
+                let configHome: String
+                if let xdg = ProcessInfo.processInfo.environment["XDG_CONFIG_HOME"], !xdg.isEmpty {
+                    configHome = xdg
+                } else {
+                    configHome = NSHomeDirectory() + "/.config"
+                }
+                return FilePath(configHome).appending("container")
+            case .appRoot:
+                if let envPath = ProcessInfo.processInfo.environment["CONTAINER_APP_ROOT"], !envPath.isEmpty {
+                    return FilePath(envPath)
+                }
+                let appSupportURL = FileManager.default.urls(
+                    for: .applicationSupportDirectory,
+                    in: .userDomainMask
+                ).first!.appendingPathComponent("com.apple.container")
+                return FilePath(appSupportURL.path(percentEncoded: false))
+            }
+        }
+    }
+}
diff --git a/Sources/ContainerPersistence/SystemRuntimeOptions.swift b/Sources/ContainerPersistence/SystemRuntimeOptions.swift
diff --git a/Sources/Plugins/CoreImages/ImagesHelper.swift b/Sources/Plugins/CoreImages/ImagesHelper.swift
diff --git a/Tests/ContainerAPIClientTests/ConfigurationLoaderTests.swift b/Tests/ContainerAPIClientTests/ConfigurationLoaderTests.swift
diff --git a/Tests/ContainerAPIClientTests/ParserTest.swift b/Tests/ContainerAPIClientTests/ParserTest.swift
diff --git a/Tests/ContainerAPIClientTests/PathUtilsTests.swift b/Tests/ContainerAPIClientTests/PathUtilsTests.swift
diff --git a/Tests/ContainerAPIClientTests/SystemRuntimeOptionsTests.swift b/Tests/ContainerAPIClientTests/SystemRuntimeOptionsTests.swift

Original file line number	Diff line number	Diff line change
`@@ -109,9 +109,7 @@ extension Application {`
`109`	`109`	`}`
`110`	`110`
`111`	`111`	`public mutating func run() async throws {`
`112`		`- let containerSystemConfig: ContainerSystemConfig = try SystemRuntimeOptions.loadConfig(`
`113`		`- configFile: SystemRuntimeOptions.configFileFromAppRoot(ApplicationRoot.url)`
`114`		`- )`
	`112`	`+ let containerSystemConfig: ContainerSystemConfig = try ConfigurationLoader.load()`
`115`	`113`	`try await DeleteImageImplementation.removeImage(options: options, containerSystemConfig: containerSystemConfig, log: log)`
`116`	`114`	`}`
`117`	`115`	`}`
Original file line number	Diff line number	Diff line change
`@@ -69,9 +69,7 @@ extension Application {`
`69`	`69`	`}`
`70`	`70`
`71`	`71`	`public func run() async throws {`
`72`		`- let containerSystemConfig: ContainerSystemConfig = try SystemRuntimeOptions.loadConfig(`
`73`		`- configFile: SystemRuntimeOptions.configFileFromAppRoot(ApplicationRoot.url)`
`74`		`- )`
	`72`	`+ let containerSystemConfig: ContainerSystemConfig = try ConfigurationLoader.load()`
`75`	`73`	`let p = try DefaultPlatform.resolve(platform: platform, os: os, arch: arch, log: log)`
`76`	`74`
`77`	`75`	`let scheme = try RequestScheme(registry.scheme)`