Merge branch 'main' into hd-return-noncopyable

Author: czechboy0

Package.swift

@@ -9,12 +9,6 @@ import Foundation
 
 let defaultTraits: Set<String> = [
     "JSONSupport"
-
-    // Disabled due to a bug in SwiftPM with traits that pull in an external dependency.
-    // Once that's fixed in Swift 6.2.x, we can enable these traits by default.
-    // Open fix: https://github.com/swiftlang/swift-package-manager/pull/9136
-    // "LoggingSupport",
-    // "ReloadingSupport",
 ]
 
 var traits: Set<Trait> = [
@@ -146,9 +140,6 @@ let package = Package(
                 "ConfigReaderTests/ConfigSnapshotReaderMethodTestsGet1.swift.gyb",
                 "ConfigReaderTests/ConfigSnapshotReaderMethodTestsGet2.swift.gyb",
                 "ConfigReaderTests/ConfigSnapshotReaderMethodTestsGet3.swift.gyb",
-            ],
-            resources: [
-                .copy("Resources")
             ]
         ),
 

Sources/Configuration/Documentation.docc/Guides/Configuring-applications.md

@@ -36,7 +36,10 @@ let logger: Logger = ...
 let config = ConfigReader(
     providers: [
         EnvironmentVariablesProvider(),
-        try await FileProvider<JSONSnapshot>(filePath: "/etc/myapp/config.json"),
+        try await FileProvider<JSONSnapshot>(
+            filePath: "/etc/myapp/config.json",
+            allowMissing: true  // Optional: treat missing file as empty config
+        ),
         InMemoryProvider(values: [
             "http.server.port": 8080,
             "http.server.host": "127.0.0.1",

Sources/Configuration/Documentation.docc/Guides/Example-use-cases.md

@@ -77,6 +77,71 @@ such as Kubernetes secrets mounted into a container's filesystem.
 
 > Tip: For comprehensive guidance on handling secrets securely, see <doc:Handling-secrets-correctly>.
 
+### Handling optional configuration files
+
+File-based providers support an `allowMissing` parameter to control whether missing files should throw an error or be treated as empty configuration. This is useful when configuration files are optional.
+
+When `allowMissing` is `false` (the default), missing files throw an error:
+
+```swift
+import Configuration
+
+// This will throw an error if config.json doesn't exist
+let config = ConfigReader(
+    provider: try await FileProvider<JSONSnapshot>(
+        filePath: "/etc/config.json",
+        allowMissing: false  // This is the default
+    )
+)
+```
+
+When `allowMissing` is `true`, missing files are treated as empty configuration:
+
+```swift
+import Configuration
+
+// This won't throw if config.json is missing - treats it as empty
+let config = ConfigReader(
+    provider: try await FileProvider<JSONSnapshot>(
+        filePath: "/etc/config.json",
+        allowMissing: true
+    )
+)
+
+// Returns the default value if the file is missing
+let port = config.int(forKey: "server.port", default: 8080)
+```
+
+The same applies to other file-based providers:
+
+```swift
+// Optional secrets directory
+let secretsConfig = ConfigReader(
+    provider: try await DirectoryFilesProvider(
+        directoryPath: "/run/secrets",
+        allowMissing: true
+    )
+)
+
+// Optional environment file
+let envConfig = ConfigReader(
+    provider: try await EnvironmentVariablesProvider(
+        environmentFilePath: "/etc/app.env",
+        allowMissing: true
+    )
+)
+
+// Optional reloading configuration
+let reloadingConfig = ConfigReader(
+    provider: try await ReloadingFileProvider<YAMLSnapshot>(
+        filePath: "/etc/dynamic-config.yaml",
+        allowMissing: true
+    )
+)
+```
+
+> Important: The `allowMissing` parameter only affects missing files. Malformed files, such as invalid JSON and YAML syntax errors will still throw parsing errors regardless of this setting.
+
 ### Setting up a fallback hierarchy
 
 Use multiple providers together to provide a configuration hierarchy that can override values at different levels.

Sources/Configuration/Documentation.docc/Guides/Troubleshooting.md

@@ -80,6 +80,45 @@ When no provider has the requested value:
 - **Methods without defaults**: Return nil.
 - **Required methods**: Throw an error.
 
+#### File not found errors
+
+File-based providers (``FileProvider``, ``ReloadingFileProvider``, ``DirectoryFilesProvider``, ``EnvironmentVariablesProvider`` with file path) can throw "file not found" errors when expected configuration files don't exist.
+
+Common scenarios and solutions:
+
+**Optional configuration files:**
+```swift
+// Problem: App crashes when optional config file is missing
+let provider = try await FileProvider<JSONSnapshot>(filePath: "/etc/optional-config.json")
+
+// Solution: Use allowMissing parameter
+let provider = try await FileProvider<JSONSnapshot>(
+    filePath: "/etc/optional-config.json",
+    allowMissing: true
+)
+```
+
+**Environment-specific files:**
+```swift
+// Different environments may have different config files
+let configPath = "/etc/\(environment)/config.json"
+let provider = try await FileProvider<JSONSnapshot>(
+    filePath: configPath,
+    allowMissing: true  // Gracefully handle missing env-specific configs
+)
+```
+
+**Container startup issues:**
+```swift
+// Config files might not be ready when container starts
+let provider = try await ReloadingFileProvider<JSONSnapshot>(
+    filePath: "/mnt/config/app.json",
+    allowMissing: true  // Allow startup with empty config, load when available
+)
+```
+
+> Important: The `allowMissing` parameter only affects missing files or directories. Files with syntax errors (invalid JSON, YAML, and so on) will still throw parsing errors.
+
 ### Reloading provider troubleshooting
 
 #### Configuration not updating

Sources/Configuration/Documentation.docc/Guides/Using-reloading-providers.md

@@ -20,6 +20,7 @@ import ServiceLifecycle
 
 let provider = try await ReloadingFileProvider<JSONSnapshot>(
     filePath: "/etc/config.json",
+    allowMissing: true,  // Optional: treat missing file as empty config
     pollInterval: .seconds(15)
 )
 
@@ -98,6 +99,58 @@ try await config.watchSnapshot { updates in
 | **Service lifecycle** | Not required | Conforms to `Service` and must run in a `ServiceGroup` |
 | **Configuration updates** | Require restart | Automatic reload |
 
+### Handling missing files during reloading
+
+Reloading providers support the `allowMissing` parameter to handle cases where configuration files might be temporarily missing or optional. This is particularly useful for:
+
+- Optional configuration files that might not exist in all environments.
+- Configuration files that are created or removed dynamically.
+- Graceful handling of file system issues during service startup.
+
+#### Missing file behavior
+
+When `allowMissing` is `false` (the default), missing files cause errors:
+
+```swift
+let provider = try await ReloadingFileProvider<JSONSnapshot>(
+    filePath: "/etc/config.json",
+    allowMissing: false  // Default: throw error if file is missing
+)
+// Will throw an error if config.json doesn't exist
+```
+
+When `allowMissing` is `true`, missing files are treated as empty configuration:
+
+```swift
+let provider = try await ReloadingFileProvider<JSONSnapshot>(
+    filePath: "/etc/config.json",
+    allowMissing: true  // Treat missing file as empty config
+)
+// Won't throw if config.json is missing - uses empty config instead
+```
+
+#### Behavior during reloading
+
+If a file becomes missing after the provider starts, the behavior depends on the `allowMissing` setting:
+
+- **`allowMissing: false`**: The provider keeps the last known configuration and logs an error.
+- **`allowMissing: true`**: The provider switches to empty configuration.
+
+In both cases, when a valid file comes back, the provider will load it and recover.
+
+```swift
+// Example: File gets deleted during runtime
+try await config.watchString(forKey: "database.host", default: "localhost") { updates in
+    for await host in updates {
+        // With allowMissing: true, this will receive "localhost" when file is removed
+        // With allowMissing: false, this keeps the last known value
+        print("Database host: \(host)")
+    }
+}
+```
+
+> Important: The `allowMissing` parameter only affects missing files. Malformed files will still cause parsing errors regardless of this setting.
+
 ### Advanced features
 
 #### Configuration-driven setup

Sources/Configuration/Documentation.docc/Reference/DirectoryFilesProvider.md

@@ -4,4 +4,4 @@
 
 ### Creating a directory files provider
 
-- ``init(directoryPath:secretsSpecifier:arraySeparator:keyEncoder:)``
+- ``init(directoryPath:allowMissing:secretsSpecifier:arraySeparator:keyEncoder:)``

Sources/Configuration/Documentation.docc/Reference/EnvironmentVariablesProvider.md

@@ -6,7 +6,7 @@
 
 - ``init(secretsSpecifier:bytesDecoder:arraySeparator:)``
 - ``init(environmentVariables:secretsSpecifier:bytesDecoder:arraySeparator:)``
-- ``init(environmentFilePath:secretsSpecifier:bytesDecoder:arraySeparator:)``
+- ``init(environmentFilePath:allowMissing:secretsSpecifier:bytesDecoder:arraySeparator:)``
 
 ### Inspecting an environment variable provider
 

Sources/Configuration/Documentation.docc/Reference/FileProvider.md

@@ -4,7 +4,7 @@
 
 ### Creating a file provider
 
-- ``init(snapshotType:parsingOptions:filePath:)``
+- ``init(snapshotType:parsingOptions:filePath:allowMissing:)``
 - ``init(snapshotType:parsingOptions:config:)``
 
 ### Reading configuration files

Sources/Configuration/Documentation.docc/Reference/ReloadingFileProvider.md

@@ -4,7 +4,7 @@
 
 ### Creating a reloading file provider
 
-- ``init(snapshotType:parsingOptions:filePath:pollInterval:logger:metrics:)``
+- ``init(snapshotType:parsingOptions:filePath:allowMissing:pollInterval:logger:metrics:)``
 - ``init(snapshotType:parsingOptions:config:logger:metrics:)``
 
 ### Service lifecycle

Sources/Configuration/Providers/EnvironmentVariables/EnvironmentVariablesProvider.swift

@@ -147,20 +147,6 @@ public struct EnvironmentVariablesProvider: Sendable {
     /// The underlying snapshot of the provider.
     private let _snapshot: Snapshot
 
-    /// The error thrown by the provider.
-    enum ProviderError: Error, CustomStringConvertible {
-
-        /// The environment file was not found at the provided path.
-        case environmentFileNotFound(path: FilePath)
-
-        var description: String {
-            switch self {
-            case .environmentFileNotFound(let path):
-                return "EnvironmentVariablesProvider: File not found at path: \(path)."
-            }
-        }
-    }
-
     /// Creates a new provider that reads from the current process environment.
     ///
     /// This initializer creates a provider that sources configuration values from
@@ -239,44 +225,80 @@ public struct EnvironmentVariablesProvider: Sendable {
 
     /// Creates a new provider that reads from an environment file.
     ///
-    /// This initializer loads environment variables from a `.env` file at the specified path.
+    /// This initializer loads environment variables from an `.env` file at the specified path.
     /// The file should contain key-value pairs in the format `KEY=value`, one per line.
     /// Comments (lines starting with `#`) and empty lines are ignored.
     ///
     /// ```swift
     /// // Load from a .env file
     /// let provider = try await EnvironmentVariablesProvider(
     ///     environmentFilePath: ".env",
+    ///     allowMissing: true,
     ///     secretsSpecifier: .specific(["API_KEY"])
     /// )
     /// ```
     ///
     /// - Parameters:
     ///   - environmentFilePath: The file system path to the environment file to load.
+    ///   - allowMissing: A flag controlling how the provider handles a missing file.
+    ///     - When `false` (the default), if the file is missing or malformed, throws an error.
+    ///     - When `true`, if the file is missing, treats it as empty. Malformed files still throw an error.
     ///   - secretsSpecifier: Specifies which environment variables should be treated as secrets.
     ///   - bytesDecoder: The decoder used for converting string values to byte arrays.
     ///   - arraySeparator: The character used to separate elements in array values.
-    /// - Throws: If the file cannot be found or read.
+    /// - Throws: If the file is malformed, or if missing when allowMissing is `false`.
     public init(
         environmentFilePath: FilePath,
+        allowMissing: Bool = false,
         secretsSpecifier: SecretsSpecifier<String, String> = .none,
         bytesDecoder: some ConfigBytesFromStringDecoder = .base64,
         arraySeparator: Character = ","
     ) async throws {
-        do {
-            let contents = try String(
-                contentsOfFile: environmentFilePath.string,
-                encoding: .utf8
-            )
-            self.init(
-                environmentVariables: EnvironmentFileParser.parsed(contents),
-                secretsSpecifier: secretsSpecifier,
-                bytesDecoder: bytesDecoder,
-                arraySeparator: arraySeparator
-            )
-        } catch let error where error.isFileNotFoundError {
-            throw ProviderError.environmentFileNotFound(path: environmentFilePath)
+        try await self.init(
+            environmentFilePath: environmentFilePath,
+            allowMissing: allowMissing,
+            fileSystem: LocalCommonProviderFileSystem(),
+            secretsSpecifier: secretsSpecifier,
+            bytesDecoder: bytesDecoder,
+            arraySeparator: arraySeparator
+        )
+    }
+
+    /// Creates a new provider that reads from an environment file.
+    /// - Parameters:
+    ///   - environmentFilePath: The file system path to the environment file to load.
+    ///   - allowMissing: A flag controlling how the provider handles a missing file.
+    ///     - When `false` (the default), if the file is missing or malformed, throws an error.
+    ///     - When `true`, if the file is missing, treats it as empty. Malformed files still throw an error.
+    ///   - fileSystem: The file system implementation to use.
+    ///   - secretsSpecifier: Specifies which environment variables should be treated as secrets.
+    ///   - bytesDecoder: The decoder used for converting string values to byte arrays.
+    ///   - arraySeparator: The character used to separate elements in array values.
+    /// - Throws: If the file is malformed, or if missing when allowMissing is `false`.
+    internal init(
+        environmentFilePath: FilePath,
+        allowMissing: Bool,
+        fileSystem: some CommonProviderFileSystem,
+        secretsSpecifier: SecretsSpecifier<String, String> = .none,
+        bytesDecoder: some ConfigBytesFromStringDecoder = .base64,
+        arraySeparator: Character = ","
+    ) async throws {
+        let loadedData = try await fileSystem.fileContents(atPath: environmentFilePath)
+        let data: Data
+        if let loadedData {
+            data = loadedData
+        } else if allowMissing {
+            data = Data()
+        } else {
+            throw FileSystemError.fileNotFound(path: environmentFilePath)
         }
+        let contents = String(decoding: data, as: UTF8.self)
+        self.init(
+            environmentVariables: EnvironmentFileParser.parsed(contents),
+            secretsSpecifier: secretsSpecifier,
+            bytesDecoder: bytesDecoder,
+            arraySeparator: arraySeparator
+        )
     }
 
     /// Returns the raw string value for a specific environment variable name.
@@ -317,23 +339,6 @@ internal struct EnvironmentValueArrayDecoder {
     }
 }
 
-extension Error {
-    /// Inspects whether the error represents a file not found.
-    internal var isFileNotFoundError: Bool {
-        if let posixError = self as? POSIXError {
-            return posixError.code == POSIXError.Code.ENOENT
-        }
-        if let cocoaError = self as? CocoaError, cocoaError.isFileError {
-            return [
-                CocoaError.fileNoSuchFile,
-                CocoaError.fileReadNoSuchFile,
-            ]
-            .contains(cocoaError.code)
-        }
-        return false
-    }
-}
-
 @available(Configuration 1.0, *)
 extension EnvironmentVariablesProvider: CustomStringConvertible {
     // swift-format-ignore: AllPublicDeclarationsHaveDocumentation