[Experimental] Generic file providers

Package.swift

@@ -29,7 +29,7 @@ var traits: Set<Trait> = [
     .trait(
         name: "ReloadingSupport",
         description:
-            "Adds support for reloading built-in provider variants, such as ReloadingJSONProvider and ReloadingYAMLProvider (when their respective traits are enabled).",
+            "Adds support for reloading built-in provider variants, such as ReloadingFileProvider.",
         enabledTraits: [
             "LoggingSupport"
         ]

README.md

@@ -43,7 +43,7 @@ The example code below creates the two relevant providers, and resolves them in
 ```swift
 let config = ConfigReader(providers: [
     EnvironmentVariablesProvider(),
-    try await JSONProvider(filePath: "/etc/config.json")
+    try await FileProvider<JSONSnapshot>(filePath: "/etc/config.json")
 ])
 let httpTimeout = config.int(forKey: "http.timeout", default: 60)
 print(httpTimeout) // prints 15
@@ -100,11 +100,11 @@ To enable an additional trait on the package, update the package dependency:
 ```
 
 Available traits:
-- **`JSONSupport`** (default): Adds support for `JSONProvider`, a `ConfigProvider` for reading JSON files.
+- **`JSONSupport`** (default): Adds support for `FileProvider<JSONSnapshot>`, a `ConfigProvider` for reading JSON files.
 - **`LoggingSupport`** (opt-in): Adds support for `AccessLogger`, a way to emit access events into a `SwiftLog.Logger`.
-- **`ReloadingSupport`** (opt-in): Adds support for auto-reloading variants of file providers, such as `ReloadingJSONProvider` (when `JSONSupport` is enabled) and `ReloadingYAMLProvider` (when `YAMLSupport` is enabled).
+- **`ReloadingSupport`** (opt-in): Adds support for auto-reloading variants of file providers, such as `ReloadingFileProvider<JSONSnapshot>` (when `JSONSupport` is enabled) and `ReloadingFileProvider<YAMLSnapshot>` (when `YAMLSupport` is enabled).
 - **`CommandLineArgumentsSupport`** (opt-in): Adds support for `CommandLineArgumentsProvider` for parsing command line arguments.
-- **`YAMLSupport`** (opt-in): Adds support for `YAMLProvider`, a `ConfigProvider` for reading YAML files.
+- **`YAMLSupport`** (opt-in): Adds support for `FileProvider<YAMLSnapshot>`, a `ConfigProvider` for reading YAML files.
 
 ## Supported platforms and minimum versions
 
@@ -120,8 +120,8 @@ The library includes comprehensive built-in provider support:
 
 - Environment variables: [`EnvironmentVariablesProvider`](https://swiftpackageindex.com/apple/swift-configuration/documentation/configuration/environmentvariablesprovider)
 - Command-line arguments: [`CommandLineArgumentsProvider`](https://swiftpackageindex.com/apple/swift-configuration/documentation/configuration/commandlineargumentsprovider)
-- JSON file: [`JSONProvider`](https://swiftpackageindex.com/apple/swift-configuration/documentation/configuration/jsonprovider) and [`ReloadingJSONProvider`](https://swiftpackageindex.com/apple/swift-configuration/documentation/configuration/reloadingjsonprovider)
-- YAML file: [`YAMLProvider`](https://swiftpackageindex.com/apple/swift-configuration/documentation/configuration/yamlprovider) and [`ReloadingYAMLProvider`](https://swiftpackageindex.com/apple/swift-configuration/documentation/configuration/reloadingyamlprovider)
+- JSON file: [`FileProvider<JSONSnapshot>`](https://swiftpackageindex.com/apple/swift-configuration/documentation/configuration/fileprovider) and [`ReloadingFileProvider<JSONSnapshot>`](https://swiftpackageindex.com/apple/swift-configuration/documentation/configuration/reloadingfileprovider)
+- YAML file: [`FileProvider<YAMLSnapshot>`](https://swiftpackageindex.com/apple/swift-configuration/documentation/configuration/fileprovider) and [`ReloadingFileProvider<YAMLSnapshot>`](https://swiftpackageindex.com/apple/swift-configuration/documentation/configuration/reloadingfileprovider)
 - Directory of files: [`DirectoryFilesProvider`](https://swiftpackageindex.com/apple/swift-configuration/documentation/configuration/directoryfilesprovider)
 - In-memory: [`InMemoryProvider`](https://swiftpackageindex.com/apple/swift-configuration/documentation/configuration/inmemoryprovider) and [`MutableInMemoryProvider`](https://swiftpackageindex.com/apple/swift-configuration/documentation/configuration/mutableinmemoryprovider)
 - Key transforming: [`KeyMappingProvider`](https://swiftpackageindex.com/apple/swift-configuration/documentation/configuration/keymappingprovider)

Sources/Configuration/ConfigReader.swift

@@ -44,7 +44,7 @@ import Foundation
 ///         // First, check environment variables
 ///         EnvironmentVariablesProvider(),
 ///         // Then, check a JSON config file
-///         try await JSONProvider(filePath: "/etc/config.json"),
+///         try await FileProvider<JSONSnapshot>(filePath: "/etc/config.json"),
 ///         // Finally, fall back to in-memory defaults
 ///         InMemoryProvider(values: [
 ///             "http.timeout": 60,

Sources/Configuration/Documentation.docc/Documentation.md

@@ -44,7 +44,7 @@ For example, to read the timeout configuration value for an HTTP client, check o
         }
         ```
         ```swift
-        let provider = try await JSONProvider(
+        let provider = try await FileProvider<JSONSnapshot>(
             filePath: "/etc/config.json"
         )
         let config = ConfigReader(provider: provider)
@@ -61,7 +61,7 @@ For example, to read the timeout configuration value for an HTTP client, check o
         }
         ```
         ```swift
-        let provider = try await ReloadingJSONProvider(
+        let provider = try await ReloadingFileProvider<JSONSnapshot>(
             filePath: "/etc/config.json"
         )
         // Omitted: Add `provider` to a ServiceGroup
@@ -76,7 +76,7 @@ For example, to read the timeout configuration value for an HTTP client, check o
           timeout: 30
         ```
         ```swift
-        let provider = try await YAMLProvider(
+        let provider = try await FileProvider<YAMLSnapshot>(
             filePath: "/etc/config.yaml"
         )
         let config = ConfigReader(provider: provider)
@@ -90,7 +90,7 @@ For example, to read the timeout configuration value for an HTTP client, check o
           timeout: 30
         ```
         ```swift
-        let provider = try await ReloadingYAMLProvider(
+        let provider = try await ReloadingFileProvider<YAMLSnapshot>(
             filePath: "/etc/config.yaml"
         )
         // Omitted: Add `provider` to a ServiceGroup
@@ -187,11 +187,11 @@ To enable an additional trait on the package, update the package dependency:
 ```
 
 Available traits:
-- **`JSONSupport`** (default): Adds support for ``JSONProvider``, a ``ConfigProvider`` for reading JSON files.
+- **`JSONSupport`** (default): Adds support for ``JSONSnapshot``, which enables using ``FileProvider`` and ``ReloadingFileProvider`` with JSON files.
 - **`LoggingSupport`** (opt-in): Adds support for ``AccessLogger``, a way to emit access events into a `SwiftLog.Logger`.
-- **`ReloadingSupport`** (opt-in): Adds support for auto-reloading variants of file providers, such as ``ReloadingJSONProvider`` (when `JSONSupport` is enabled) and ``ReloadingYAMLProvider`` (when `YAMLSupport` is enabled).
+- **`ReloadingSupport`** (opt-in): Adds support for ``ReloadingFileProvider``, which provides auto-reloading capability for file-based configuration.
 - **`CommandLineArgumentsSupport`** (opt-in): Adds support for ``CommandLineArgumentsProvider`` for parsing command line arguments.
-- **`YAMLSupport`** (opt-in): Adds support for ``YAMLProvider``, a ``ConfigProvider`` for reading YAML files.
+- **`YAMLSupport`** (opt-in): Adds support for ``YAMLSnapshot``, which enables using ``FileProvider`` and ``ReloadingFileProvider`` with YAML files.
 
 ### Supported platforms and minimum versions
 
@@ -235,8 +235,8 @@ The library includes comprehensive built-in provider support:
 
 - Environment variables: ``EnvironmentVariablesProvider``
 - Command-line arguments: ``CommandLineArgumentsProvider``
-- JSON file: ``JSONProvider`` and ``ReloadingJSONProvider``
-- YAML file: ``YAMLProvider`` and ``ReloadingYAMLProvider``
+- JSON file: ``FileProvider`` and ``ReloadingFileProvider`` with ``JSONSnapshot``
+- YAML file: ``FileProvider`` and ``ReloadingFileProvider`` with ``YAMLSnapshot``
 - Directory of files: ``DirectoryFilesProvider``
 - In-memory: ``InMemoryProvider`` and ``MutableInMemoryProvider``
 - Key transforming: ``KeyMappingProvider``
@@ -259,7 +259,7 @@ let config = ConfigReader(providers: [
     // Then, check command-line options.
     CommandLineArgumentsProvider(),
     // Then, check a JSON config file.
-    try await JSONProvider(filePath: "/etc/config.json"),
+    try await FileProvider<JSONSnapshot>(filePath: "/etc/config.json"),
     // Finally, fall back to in-memory defaults.
     InMemoryProvider(values: [
         "http.timeout": 60,
@@ -272,10 +272,10 @@ let timeout = config.int(forKey: "http.timeout", default: 15)
 
 #### Hot reloading
 
-Long-running services can periodically reload configuration with ``ReloadingJSONProvider`` and ``ReloadingYAMLProvider``:
+Long-running services can periodically reload configuration with ``ReloadingFileProvider``:
 
 ```swift
-let provider = try await ReloadingJSONProvider(filePath: "/etc/config.json")
+let provider = try await ReloadingFileProvider<JSONSnapshot>(filePath: "/etc/config.json")
 // Omitted: add provider to a ServiceGroup
 let config = ConfigReader(provider: provider)
 
@@ -407,18 +407,17 @@ Any package can implement a ``ConfigProvider``, making the ecosystem extensible
 - ``ConfigReader``
 - ``ConfigProvider``
 - ``ConfigSnapshotReader``
-- ``ConfigSnapshotProtocol``
 - <doc:Choosing-access-patterns>
 - <doc:Choosing-reader-methods>
 - <doc:Handling-secrets-correctly>
 
 ### Built-in providers
 - ``EnvironmentVariablesProvider``
 - ``CommandLineArgumentsProvider``
-- ``JSONProvider``
-- ``YAMLProvider``
-- ``ReloadingJSONProvider``
-- ``ReloadingYAMLProvider``
+- ``FileProvider``
+- ``ReloadingFileProvider``
+- ``JSONSnapshot``
+- ``YAMLSnapshot``
 - <doc:Using-reloading-providers>
 - ``DirectoryFilesProvider``
 - <doc:Using-in-memory-providers>
@@ -427,6 +426,8 @@ Any package can implement a ``ConfigProvider``, making the ecosystem extensible
 - ``KeyMappingProvider``
 
 ### Creating a custom provider
+- ``ConfigSnapshotProtocol``
+- ``FileParsingOptionsProtocol``
 - ``ConfigProvider``
 - ``ConfigContent``
 - ``ConfigValue``

Sources/Configuration/Documentation.docc/Guides/Choosing-access-patterns.md

@@ -122,7 +122,7 @@ Use the "watch" pattern when:
 
 - Immediately emits the initial value, then subsequent updates.
 - Continues monitoring until the task is cancelled.
-- Works with providers like ``ReloadingJSONProvider`` and ``ReloadingYAMLProvider``.
+- Works with providers like ``ReloadingFileProvider``.
 
 For details on reloading providers, check out <doc:Using-reloading-providers>.
 

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

@@ -35,8 +35,8 @@ let logger: Logger = ...
 
 let config = ConfigReader(
     providers: [
-        EnvironmentVariablesProvider(), 
-        try await JSONProvider(filePath: "/etc/myapp/config.json"), 
+        EnvironmentVariablesProvider(),
+        try await FileProvider<JSONSnapshot>(filePath: "/etc/myapp/config.json"),
         InMemoryProvider(values: [
             "http.server.port": 8080,
             "http.server.host": "127.0.0.1",

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

@@ -24,15 +24,15 @@ variable name above `SERVER_PORT`.
 
 ### Reading from a JSON configuration file
 
-You can store multiple configuration values together in a JSON file and read them from the fileystem using ``JSONProvider``.
+You can store multiple configuration values together in a JSON file and read them from the fileystem using ``FileProvider`` with ``JSONSnapshot``.
 The following example creates a ``ConfigReader`` for a JSON file at the path `/etc/config.json`, and reads a url and port
 number collected as properties of the `database` JSON object:
 
 ```swift
 import Configuration
 
 let config = ConfigReader(
-    provider: try await JSONProvider(filePath: "/etc/config.json")
+    provider: try await FileProvider<JSONSnapshot>(filePath: "/etc/config.json")
 )
 
 // Access nested values using dot notation.
@@ -92,7 +92,7 @@ let config = ConfigReader(providers: [
     // First check environment variables.
     EnvironmentVariablesProvider(),
     // Then check the config file.
-    try await JSONProvider(filePath: "/etc/config.json"),
+    try await FileProvider<JSONSnapshot>(filePath: "/etc/config.json"),
     // Finally, use hardcoded defaults.
     InMemoryProvider(values: [
         "app.name": "MyApp",
@@ -131,7 +131,7 @@ import Configuration
 import ServiceLifecycle
 
 // Create a reloading YAML provider
-let provider = try await ReloadingYAMLProvider(
+let provider = try await ReloadingFileProvider<YAMLSnapshot>(
     filePath: "/etc/app-config.yaml",
     pollInterval: .seconds(30)
 )

Sources/Configuration/Documentation.docc/Guides/Handling-secrets-correctly.md

@@ -81,7 +81,7 @@ The following example marks keys as secret based on the closure you provide.
 In this case, keys that contain `password`, `secret`, or `token` are all marked as secret:
 
 ```swift
-let provider = JSONProvider(
+let provider = FileProvider<JSONSnapshot>(
     filePath: "/etc/config.json",
     secretsSpecifier: .dynamic { key, value in
         key.lowercased().contains("password") ||
@@ -96,7 +96,7 @@ let provider = JSONProvider(
 The following example asserts that none of the values returned from the provider are considered secret:
 
 ```swift
-let provider = JSONProvider(
+let provider = FileProvider<JSONSnapshot>(
     filePath: "/etc/config.json",
     secretsSpecifier: .none
 )

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

@@ -99,12 +99,12 @@ Common ServiceGroup problems:
 
 ```swift
 // Incorrect: Provider not included in ServiceGroup
-let provider = try await ReloadingJSONProvider(filePath: "/etc/config.json")
+let provider = try await ReloadingFileProvider<JSONSnapshot>(filePath: "/etc/config.json")
 let config = ConfigReader(provider: provider)
 // File monitoring won't work
 
 // Correct: Provider runs in ServiceGroup
-let provider = try await ReloadingJSONProvider(filePath: "/etc/config.json")
+let provider = try await ReloadingFileProvider<JSONSnapshot>(filePath: "/etc/config.json")
 let serviceGroup = ServiceGroup(services: [provider], logger: logger)
 try await serviceGroup.run()
 ```

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

@@ -6,8 +6,8 @@ Automatically reload configuration from files when they change.
 
 A reloading provider monitors configuration files for changes and automatically updates your application's configuration without requiring restarts. Swift Configuration provides:
 
-- ``ReloadingJSONProvider`` for JSON configuration files.
-- ``ReloadingYAMLProvider`` for YAML configuration files.
+- ``ReloadingFileProvider`` with ``JSONSnapshot`` for JSON configuration files.
+- ``ReloadingFileProvider`` with ``YAMLSnapshot`` for YAML configuration files.
 
 ### Basic usage
 
@@ -18,7 +18,7 @@ Reloading providers run in a [`ServiceGroup`](https://swiftpackageindex.com/swif
 ```swift
 import ServiceLifecycle
 
-let provider = try await ReloadingJSONProvider(
+let provider = try await ReloadingFileProvider<JSONSnapshot>(
     filePath: "/etc/config.json",
     pollInterval: .seconds(15)
 )
@@ -109,8 +109,8 @@ and interval to watch for a JSON file that contains the configuration for your a
 let envProvider = EnvironmentVariablesProvider()
 let envConfig = ConfigReader(provider: envProvider)
 
-let jsonProvider = try await ReloadingJSONProvider(
-    config: envConfig.scoped(to: "json")  
+let jsonProvider = try await ReloadingFileProvider<JSONSnapshot>(
+    config: envConfig.scoped(to: "json")
     // Reads JSON_FILE_PATH and JSON_POLL_INTERVAL_SECONDS
 )
 ```
@@ -120,10 +120,10 @@ let jsonProvider = try await ReloadingJSONProvider(
 1. **Replace initialization**:
    ```swift
    // Before
-   let provider = try await JSONProvider(filePath: "/etc/config.json")
+   let provider = try await FileProvider<JSONSnapshot>(filePath: "/etc/config.json")
 
    // After
-   let provider = try await ReloadingJSONProvider(filePath: "/etc/config.json")
+   let provider = try await ReloadingFileProvider<JSONSnapshot>(filePath: "/etc/config.json")
    ```
 
 2. **Add the provider to a ServiceGroup**:

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

@@ -0,0 +1,12 @@
+# ``Configuration/FileConfigSnapshotProtocol``
+
+## Topics
+
+### Required methods
+
+- ``init(data:providerName:parsingOptions:)``
+- ``ParsingOptions``
+
+### Protocol requirements
+
+- ``ConfigSnapshotProtocol``

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

@@ -0,0 +1,11 @@
+# ``Configuration/FileParsingOptionsProtocol``
+
+## Topics
+
+### Required properties
+
+- ``default``
+
+### Parsing options
+
+- ``FileConfigSnapshotProtocol``

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

@@ -0,0 +1,14 @@
+# ``Configuration/FileProvider``
+
+## Topics
+
+### Creating a file provider
+
+- ``init(snapshotType:parsingOptions:filePath:)``
+- ``init(snapshotType:parsingOptions:config:)``
+
+### Reading configuration files
+
+- ``FileConfigSnapshotProtocol``
+- ``JSONSnapshot``
+- ``YAMLSnapshot``

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

@@ -0,0 +1,13 @@
+# ``Configuration/JSONSnapshot``
+
+## Topics
+
+### Creating a JSON snapshot
+
+- ``init(data:providerName:parsingOptions:)``
+- ``ParsingOptions``
+
+### Snapshot configuration
+
+- ``FileConfigSnapshotProtocol``
+- ``ConfigSnapshotProtocol``

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

@@ -0,0 +1,18 @@
+# ``Configuration/ReloadingFileProvider``
+
+## Topics
+
+### Creating a reloading file provider
+
+- ``init(snapshotType:parsingOptions:filePath:pollInterval:logger:metrics:)``
+- ``init(snapshotType:parsingOptions:config:logger:metrics:)``
+
+### Service lifecycle
+
+- ``run()``
+
+### Monitoring file changes
+
+- ``FileConfigSnapshotProtocol``
+- ``JSONSnapshot``
+- ``YAMLSnapshot``