chore: import upstream snapshot with attribution

Sources/ContainerLog/FileLogHandler.swift

@@ -0,0 +1,101 @@
+//===----------------------------------------------------------------------===//
+// 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 Logging
+import SystemPackage
+
+/// Log handler that appends messages to a file, without any
+/// rotation or truncation strategy. Use for development purposes only.
+public struct FileLogHandler: LogHandler {
+    public var logLevel: Logger.Level = .info
+    public var metadata: Logger.Metadata = [:]
+
+    private let label: String
+    private let category: String
+    private let fileHandle: FileHandle
+
+    public subscript(metadataKey metadataKey: String) -> Logger.Metadata.Value? {
+        get {
+            self.metadata[metadataKey]
+        }
+        set {
+            self.metadata[metadataKey] = newValue
+        }
+    }
+
+    /// Create a log handler that appends to the specified file.
+    ///
+    /// - Parameters:
+    ///   - label: A unique identifier for the application.
+    ///   - category: An identifier for the application subsystem.
+    ///   - path: The log file location. The log handler creates the
+    ///     file and parent directory if needed.
+    /// - Returns: The log handler.
+    public init(label: String, category: String, path: FilePath) throws {
+        self.label = label
+        self.category = category
+        let parentPath = path.removingLastComponent()
+        try FileManager.default.createDirectory(atPath: parentPath.string, withIntermediateDirectories: true)
+        if !FileManager.default.fileExists(atPath: path.string) {
+            FileManager.default.createFile(atPath: path.string, contents: nil)
+        }
+        guard let handle = FileHandle(forWritingAtPath: path.string) else {
+            throw FileLogFailure.openFailed
+        }
+        self.fileHandle = handle
+        self.fileHandle.seekToEndOfFile()
+    }
+
+    public func log(
+        level: Logger.Level,
+        message: Logger.Message,
+        metadata: Logger.Metadata?,
+        source: String,
+        file: String,
+        function: String,
+        line: UInt
+    ) {
+        let timestampFormatter: ISO8601DateFormatter = {
+            let formatter = ISO8601DateFormatter()
+            formatter.formatOptions.insert(.withFractionalSeconds)
+            return formatter
+        }()
+        let timestamp = timestampFormatter.string(from: Date())
+
+        // Merge logger-level metadata with per-message metadata
+        var effectiveMetadata = self.metadata
+        if let metadata {
+            effectiveMetadata.merge(metadata) { _, new in new }
+        }
+
+        let text: String
+        if !effectiveMetadata.isEmpty {
+            text = "\(timestamp) [\(level)] \(label) \(category) \(effectiveMetadata.description): \(message)\n"
+        } else {
+            text = "\(timestamp) [\(level)] \(label): \(category) \(message)\n"
+        }
+        if let data = text.data(using: .utf8) {
+            fileHandle.write(data)
+        }
+    }
+
+    /// Failures relating to the log handler.
+    public enum FileLogFailure: Error {
+        /// The log handler could not open the log file.
+        case openFailed
+    }
+}

Sources/ContainerLog/OSLogHandler.swift

@@ -0,0 +1,104 @@
+//===----------------------------------------------------------------------===//
+// Copyright © 2025-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 Logging
+import os
+
+import struct Logging.Logger
+
+public struct OSLogHandler: LogHandler {
+    private let logger: os.Logger
+
+    public var logLevel: Logger.Level = .info
+    private var formattedMetadata: String?
+
+    public var metadata = Logger.Metadata() {
+        didSet {
+            self.formattedMetadata = self.formatMetadata(self.metadata)
+        }
+    }
+
+    public subscript(metadataKey metadataKey: String) -> Logger.Metadata.Value? {
+        get {
+            self.metadata[metadataKey]
+        }
+        set {
+            self.metadata[metadataKey] = newValue
+        }
+    }
+
+    public init(label: String, category: String) {
+        self.logger = os.Logger(subsystem: label, category: category)
+    }
+}
+
+extension OSLogHandler {
+    public func log(
+        level: Logger.Level,
+        message: Logger.Message,
+        metadata: Logger.Metadata?,
+        source: String,
+        file: String,
+        function: String,
+        line: UInt
+    ) {
+        var formattedMetadata = self.formattedMetadata
+        if let metadataOverride = metadata, !metadataOverride.isEmpty {
+            formattedMetadata = self.formatMetadata(
+                self.metadata.merging(metadataOverride) {
+                    $1
+                }
+            )
+        }
+
+        var finalMessage = message.description
+        if let formattedMetadata {
+            finalMessage += " " + formattedMetadata
+        }
+
+        self.logger.log(
+            level: level.toOSLogLevel(),
+            "\(finalMessage, privacy: .public)"
+        )
+    }
+
+    private func formatMetadata(_ metadata: Logger.Metadata) -> String? {
+        if metadata.isEmpty {
+            return nil
+        }
+        return metadata.map {
+            "[\($0)=\($1)]"
+        }.joined(separator: " ")
+    }
+}
+
+extension Logger.Level {
+    func toOSLogLevel() -> OSLogType {
+        switch self {
+        case .debug, .trace:
+            return .debug
+        case .info:
+            return .info
+        case .notice, .warning:
+            return .default
+        case .error:
+            return .error
+        case .critical:
+            return .fault
+        }
+    }
+}

Sources/ContainerLog/ServiceLogger.swift

@@ -0,0 +1,74 @@
+//===----------------------------------------------------------------------===//
+// 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 Logging
+import SystemPackage
+
+/// Common logging setup for application services.
+public struct ServiceLogger {
+    /// Set up the logging system and create a root logger.
+    ///
+    /// - Parameters:
+    ///   - label: A unique identifier for the application.
+    ///   - category: An identifier for the application subsystem.
+    ///   - metadata: Metadata to include for all messsages. A message
+    ///     specific value for a duplicate key overrides these values.
+    ///   - debug: Enable debug logging.
+    ///   - logPath: If supplied, create log files under the named
+    ///     directory. Otherwise, log to the OS log facility.
+    /// - Returns: The root logger.
+    public static func bootstrap(
+        label: String = "com.apple.container",
+        category: String,
+        metadata: [String: String] = [:],
+        debug: Bool,
+        logPath: FilePath?
+    ) -> Logger {
+        // Select the log handler and bootstrap logging.
+        LoggingSystem.bootstrap { label in
+            if let logPath {
+                if let handler = try? FileLogHandler(
+                    label: label,
+                    category: category,
+                    path: logPath
+                ) {
+                    return handler
+                }
+            }
+            return OSLogHandler(label: label, category: category)
+        }
+
+        // Configure log level and metadata.
+        var log = Logger(label: label)
+        if debug {
+            log.logLevel = .debug
+        }
+        for (key, value) in metadata {
+            log[metadataKey: key] = "\(value)"
+        }
+
+        // Log an error if for some reason FileLogHandler init failed.
+        if let logPath, log.handler as? OSLogHandler != nil {
+            log.error(
+                "unable to initialize FileLogHandler, using OSLogHandler",
+                metadata: [
+                    "logPath": "\(logPath)"
+                ])
+        }
+
+        return log
+    }
+}

Sources/ContainerLog/StderrLogHandler.swift

@@ -0,0 +1,87 @@
+//===----------------------------------------------------------------------===//
+// Copyright © 2025-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 Logging
+
+/// Basic log handler for where simple message output is needed,
+/// such as CLI commands.
+public struct StderrLogHandler: LogHandler {
+    public var logLevel: Logger.Level = .info
+    public var metadata: Logger.Metadata = [:]
+
+    public subscript(metadataKey metadataKey: String) -> Logger.Metadata.Value? {
+        get {
+            self.metadata[metadataKey]
+        }
+        set {
+            self.metadata[metadataKey] = newValue
+        }
+    }
+
+    public init() {}
+
+    public func log(
+        level: Logger.Level,
+        message: Logger.Message,
+        metadata: Logger.Metadata?,
+        source: String,
+        file: String,
+        function: String,
+        line: UInt
+    ) {
+        let data: Data
+        switch logLevel {
+        case .debug, .trace:
+            let timestamp = isoTimestamp()
+            if let metadata, !metadata.isEmpty {
+                data =
+                    "\(timestamp) \(message.description): \(metadata.description)\n"
+                    .data(using: .utf8) ?? Data()
+            } else {
+                data =
+                    "\(timestamp) \(message.description)\n"
+                    .data(using: .utf8) ?? Data()
+            }
+        default:
+            if let metadata, !metadata.isEmpty {
+                data =
+                    "\(message.description): \(metadata.description)\n"
+                    .data(using: .utf8) ?? Data()
+            } else {
+                data =
+                    "\(message.description)\n"
+                    .data(using: .utf8) ?? Data()
+            }
+        }
+
+        FileHandle.standardError.write(data)
+    }
+
+    private func isoTimestamp() -> String {
+        let date = Date()
+        var time = time_t(date.timeIntervalSince1970)
+        var ms = Int(date.timeIntervalSince1970 * 1000) % 1000
+        if ms < 0 { ms += 1000 }
+        var tm = tm()
+        gmtime_r(&time, &tm)
+        let buf = withUnsafeTemporaryAllocation(of: CChar.self, capacity: 32) { ptr -> String in
+            strftime(ptr.baseAddress!, 32, "%Y-%m-%dT%H:%M:%S", &tm)
+            return String(cString: ptr.baseAddress!)
+        }
+        return String(format: "%@.%03dZ", buf, ms)
+    }
+}