Fixes for install root and plugin detection. (#467)

jglogan · web-flow · commit 6242706c66c4 · 2025-08-08T21:44:26.000-07:00
- Sets up API server as source of truth for installation root, similarly
to what was done for the data root. `system start` establishes the
install root, setting the environment variable `CONTAINER_INSTALL_ROOT`
when launching the API server.
- The API server propagates the environment variable when launching
helpers, and returns the install root to the CLI via the health check
XPC.
- Includes several fixes for detecting plugins that use app bundle
layout.
diff --git a/Package.swift b/Package.swift
@@ -223,11 +223,11 @@ let package = Package(
                 .product(name: "ContainerizationOCI", package: "containerization"),
                 .product(name: "ContainerizationOS", package: "containerization"),
                 .product(name: "ArgumentParser", package: "swift-argument-parser"),
-                "ContainerNetworkService",
-                "ContainerPersistence",
                 "ContainerImagesServiceClient",
-                "TerminalProgress",
+                "ContainerNetworkService",
+                "ContainerPlugin",
                 "ContainerXPC",
+                "TerminalProgress",
             ]
         ),
         .testTarget(
diff --git a/Sources/APIServer/APIServer.swift b/Sources/APIServer/APIServer.swift
@@ -45,6 +45,8 @@ struct APIServer: AsyncParsableCommand {
 
     var appRoot = ApplicationRoot.url
 
+    var installRoot = InstallRoot.url
+
     static func releaseVersion() -> String {
         (Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String) ?? get_release_version().map { String(cString: $0) } ?? "0.0.0"
     }
@@ -124,11 +126,11 @@ struct APIServer: AsyncParsableCommand {
     }
 
     private func initializePluginLoader(log: Logger) throws -> PluginLoader {
-        let installRoot = CommandLine.executablePathUrl
-            .deletingLastPathComponent()
-            .appendingPathComponent("..")
-            .standardized
-        log.info("initializing plugin loader", metadata: ["installRoot": "\(installRoot.path(percentEncoded: false))"])
+        log.info(
+            "initializing plugin loader",
+            metadata: [
+                "installRoot": "\(installRoot.path(percentEncoded: false))"
+            ])
 
         let pluginsURL = PluginLoader.userPluginsDir(installRoot: installRoot)
         log.info("detecting user plugins directory", metadata: ["path": "\(pluginsURL.path(percentEncoded: false))"])
@@ -162,13 +164,11 @@ struct APIServer: AsyncParsableCommand {
             log.info("discovered plugin directory", metadata: ["path": "\(pluginDirectory.path(percentEncoded: false))"])
         }
 
-        let statePath = PluginLoader.defaultPluginResourcePath(root: appRoot)
-        try FileManager.default.createDirectory(at: statePath, withIntermediateDirectories: true)
-        return PluginLoader(
+        return try PluginLoader(
             appRoot: appRoot,
+            installRoot: installRoot,
             pluginDirectories: pluginDirectories,
             pluginFactories: pluginFactories,
-            defaultResourcePath: statePath,
             log: log
         )
     }
@@ -194,7 +194,7 @@ struct APIServer: AsyncParsableCommand {
     }
 
     private func initializeHealthCheckService(log: Logger, routes: inout [XPCRoute: XPCServer.RouteHandler]) {
-        let svc = HealthCheckHarness(appRoot: appRoot, log: log)
+        let svc = HealthCheckHarness(appRoot: appRoot, installRoot: installRoot, log: log)
         routes[XPCRoute.ping] = svc.ping
     }
 
diff --git a/Sources/APIServer/HealthCheck/HealthCheckHarness.swift b/Sources/APIServer/HealthCheck/HealthCheckHarness.swift
@@ -23,17 +23,20 @@ import Logging
 
 actor HealthCheckHarness {
     private let appRoot: URL
+    private let installRoot: URL
     private let log: Logger
 
-    public init(appRoot: URL, log: Logger) {
+    public init(appRoot: URL, installRoot: URL, log: Logger) {
         self.appRoot = appRoot
+        self.installRoot = installRoot
         self.log = log
     }
 
     @Sendable
     func ping(_ message: XPCMessage) async -> XPCMessage {
         let reply = message.reply()
         reply.set(key: .appRoot, value: appRoot.absoluteString)
+        reply.set(key: .installRoot, value: installRoot.absoluteString)
         reply.set(key: .apiServerVersion, value: APIServer.releaseVersion())
         reply.set(key: .apiServerCommit, value: get_git_commit().map { String(cString: $0) } ?? "unknown")
         return reply
diff --git a/Sources/CLI/Application.swift b/Sources/CLI/Application.swift
@@ -158,22 +158,19 @@ struct Application: AsyncParsableCommand {
             installRootPluginsURL,
         ].compactMap { $0 }
 
-        let pluginFactories = [
-            DefaultPluginFactory()
+        let pluginFactories: [any PluginFactory] = [
+            DefaultPluginFactory(),
+            AppBundlePluginFactory(),
         ]
 
         guard let systemHealth = try? await ClientHealthCheck.ping(timeout: .seconds(10)) else {
             throw ContainerizationError(.timeout, message: "unable to retrieve application data root from API server")
         }
-        let statePath = PluginLoader.defaultPluginResourcePath(root: systemHealth.appRoot)
-        guard (try? FileManager.default.createDirectory(at: statePath, withIntermediateDirectories: true)) != nil else {
-            throw ContainerizationError(.invalidState, message: "unable to create plugin state directory")
-        }
-        return PluginLoader(
+        return try PluginLoader(
             appRoot: systemHealth.appRoot,
+            installRoot: systemHealth.installRoot,
             pluginDirectories: pluginDirectories,
             pluginFactories: pluginFactories,
-            defaultResourcePath: statePath,
             log: log
         )
     }
diff --git a/Sources/CLI/System/SystemStart.swift b/Sources/CLI/System/SystemStart.swift
@@ -29,14 +29,17 @@ extension Application {
             abstract: "Start `container` services"
         )
 
-        @Option(name: .shortAndLong, help: "Path to the `container-apiserver` binary")
-        var path: String = Bundle.main.executablePath ?? ""
-
         @Option(
             name: .shortAndLong,
             help: "Application data directory",
             transform: { URL(filePath: $0) })
-        var appRoot: URL = ApplicationRoot.defaultURL
+        var appRoot = ApplicationRoot.defaultURL
+
+        @Option(
+            name: .long,
+            help: "Path to the installation root directory",
+            transform: { URL(filePath: $0) })
+        public var installRoot = InstallRoot.defaultURL
 
         @Flag(name: .long, help: "Enable debug logging for the runtime daemon.")
         var debug = false
@@ -48,10 +51,11 @@ extension Application {
 
         func run() async throws {
             // Without the true path to the binary in the plist, `container-apiserver` won't launch properly.
-            let executableUrl = URL(filePath: path)
-                .resolvingSymlinksInPath()
+            // TODO: Use plugin loader for API server.
+            let executableUrl = CommandLine.executablePathUrl
                 .deletingLastPathComponent()
                 .appendingPathComponent("container-apiserver")
+                .resolvingSymlinksInPath()
 
             var args = [executableUrl.absolutePath()]
 
@@ -64,7 +68,8 @@ extension Application {
             var env = ProcessInfo.processInfo.environment.filter { key, _ in
                 key.hasPrefix("CONTAINER_")
             }
-            env["CONTAINER_APP_ROOT"] = appRoot.path(percentEncoded: false)
+            env[ApplicationRoot.environmentName] = appRoot.path(percentEncoded: false)
+            env[InstallRoot.environmentName] = installRoot.path(percentEncoded: false)
 
             let logURL = apiServerDataUrl.appending(path: "apiserver.log")
             let plist = LaunchPlist(
diff --git a/Sources/CLI/System/SystemStatus.swift b/Sources/CLI/System/SystemStatus.swift
@@ -40,10 +40,10 @@ extension Application {
 
             // Now ping our friendly daemon. Fail after 10 seconds with no response.
             do {
-                print("Verifying apiserver is running...")
                 let systemHealth = try await ClientHealthCheck.ping(timeout: .seconds(10))
                 print("apiserver is running")
                 print("application data root: \(systemHealth.appRoot.path(percentEncoded: false))")
+                print("application install root: \(systemHealth.installRoot.path(percentEncoded: false))")
                 print("container-apiserver version: \(systemHealth.apiServerVersion)")
                 print("container-apiserver commit: \(systemHealth.apiServerCommit)")
             } catch {
diff --git a/Sources/ContainerClient/Core/ClientHealthCheck.swift b/Sources/ContainerClient/Core/ClientHealthCheck.swift
@@ -34,12 +34,15 @@ extension ClientHealthCheck {
         guard let appRootValue = reply.string(key: .appRoot), let appRoot = URL(string: appRootValue) else {
             throw ContainerizationError(.internalError, message: "failed to decode appRoot in health check")
         }
+        guard let installRootValue = reply.string(key: .installRoot), let installRoot = URL(string: installRootValue) else {
+            throw ContainerizationError(.internalError, message: "failed to decode installRoot in health check")
+        }
         guard let apiServerVersion = reply.string(key: .apiServerVersion) else {
             throw ContainerizationError(.internalError, message: "failed to decode apiServerVersion in health check")
         }
         guard let apiServerCommit = reply.string(key: .apiServerCommit) else {
             throw ContainerizationError(.internalError, message: "failed to decode apiServerCommit in health check")
         }
-        return .init(appRoot: appRoot, apiServerVersion: apiServerVersion, apiServerCommit: apiServerCommit)
+        return .init(appRoot: appRoot, installRoot: installRoot, apiServerVersion: apiServerVersion, apiServerCommit: apiServerCommit)
     }
 }
diff --git a/Sources/ContainerClient/Core/SystemHealth.swift b/Sources/ContainerClient/Core/SystemHealth.swift
@@ -21,6 +21,9 @@ public struct SystemHealth: Sendable, Codable {
     /// The full pathname of the application data root.
     public let appRoot: URL
 
+    /// The full pathname of the application install root.
+    public let installRoot: URL
+
     /// The release version of the container services.
     public let apiServerVersion: String
 
diff --git a/Sources/ContainerClient/XPC+.swift b/Sources/ContainerClient/XPC+.swift
@@ -54,6 +54,7 @@ public enum XPCKeys: String {
     /// Health check request.
     case ping
     case appRoot
+    case installRoot
     case apiServerVersion
     case apiServerCommit
 
diff --git a/Sources/ContainerPlugin/ApplicationRoot.swift b/Sources/ContainerPlugin/ApplicationRoot.swift
@@ -16,6 +16,7 @@
 
 import Foundation
 
+/// Provides the application data root path.
 public struct ApplicationRoot {
     public static let environmentName = "CONTAINER_APP_ROOT"
 
diff --git a/Sources/ContainerPlugin/InstallRoot.swift b/Sources/ContainerPlugin/InstallRoot.swift
@@ -0,0 +1,33 @@
+//===----------------------------------------------------------------------===//
+// Copyright © 2025 Apple Inc. and the container project authors. All rights reserved.
+//
+// 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
+
+/// Provides the application installation root path.
+public struct InstallRoot {
+    public static let environmentName = "CONTAINER_INSTALL_ROOT"
+
+    public static let defaultURL = CommandLine.executablePathUrl
+        .deletingLastPathComponent()
+        .appendingPathComponent("..")
+        .standardized
+
+    private static let envPath = ProcessInfo.processInfo.environment[Self.environmentName]
+
+    public static let url = envPath.map { URL(fileURLWithPath: $0) } ?? defaultURL
+
+    public static let path = url.path(percentEncoded: false)
+}
diff --git a/Sources/ContainerPlugin/PluginFactory.swift b/Sources/ContainerPlugin/PluginFactory.swift
@@ -22,8 +22,10 @@ private let configFilename: String = "config.json"
 
 /// Describes the configuration and binary file locations for a plugin.
 public protocol PluginFactory: Sendable {
-    /// Create a plugin conforming to the layout, if possible.
+    /// Create a plugin from the plugin path, if it conforms to the layout.
     func create(installURL: URL) throws -> Plugin?
+    /// Create a plugin from the plugin parent path and name, if it conforms to the layout.
+    func create(parentURL: URL, name: String) throws -> Plugin?
 }
 
 /// Default layout which uses a Unix-like structure.
@@ -50,6 +52,10 @@ public struct DefaultPluginFactory: PluginFactory {
 
         return Plugin(binaryURL: binaryURL, config: config)
     }
+
+    public func create(parentURL: URL, name: String) throws -> Plugin? {
+        try create(installURL: parentURL.appendingPathComponent(name))
+    }
 }
 
 /// Layout which uses a macOS application bundle structure.
@@ -90,4 +96,8 @@ public struct AppBundlePluginFactory: PluginFactory {
 
         return Plugin(binaryURL: binaryURL, config: config)
     }
+
+    public func create(parentURL: URL, name: String) throws -> Plugin? {
+        try create(installURL: parentURL.appendingPathComponent("\(name)\(Self.appSuffix)"))
+    }
 }
diff --git a/Sources/ContainerPlugin/PluginLoader.swift b/Sources/ContainerPlugin/PluginLoader.swift
diff --git a/Tests/ContainerPluginTests/MockPluginFactory.swift b/Tests/ContainerPluginTests/MockPluginFactory.swift
diff --git a/Tests/ContainerPluginTests/PluginFactoryTest.swift b/Tests/ContainerPluginTests/PluginFactoryTest.swift
diff --git a/Tests/ContainerPluginTests/PluginLoaderTest.swift b/Tests/ContainerPluginTests/PluginLoaderTest.swift

Original file line number	Diff line number	Diff line change
`@@ -34,12 +34,15 @@ extension ClientHealthCheck {`
`34`	`34`	`guard let appRootValue = reply.string(key: .appRoot), let appRoot = URL(string: appRootValue) else {`
`35`	`35`	`throw ContainerizationError(.internalError, message: "failed to decode appRoot in health check")`
`36`	`36`	`}`
	`37`	`+ guard let installRootValue = reply.string(key: .installRoot), let installRoot = URL(string: installRootValue) else {`
	`38`	`+ throw ContainerizationError(.internalError, message: "failed to decode installRoot in health check")`
	`39`	`+ }`
`37`	`40`	`guard let apiServerVersion = reply.string(key: .apiServerVersion) else {`
`38`	`41`	`throw ContainerizationError(.internalError, message: "failed to decode apiServerVersion in health check")`
`39`	`42`	`}`
`40`	`43`	`guard let apiServerCommit = reply.string(key: .apiServerCommit) else {`
`41`	`44`	`throw ContainerizationError(.internalError, message: "failed to decode apiServerCommit in health check")`
`42`	`45`	`}`
`43`		`- return .init(appRoot: appRoot, apiServerVersion: apiServerVersion, apiServerCommit: apiServerCommit)`
	`46`	`+ return .init(appRoot: appRoot, installRoot: installRoot, apiServerVersion: apiServerVersion, apiServerCommit: apiServerCommit)`
`44`	`47`	`}`
`45`	`48`	`}`