ReloadingFileProvider

A configuration provider that reads configuration from a file on disk with automatic reloading capability.

iOS 18.0+
macOS 15.0+
tvOS 18.0+
visionOS 2.0+
watchOS 11.0+

final class ReloadingFileProvider<Snapshot> where Snapshot : FileConfigSnapshot

Mentioned In

Overview

ReloadingFileProvider is a generic file-based configuration provider that monitors a configuration file for changes and automatically reloads the data when the file is modified. This provider works with different file formats by using different snapshot types that conform to FileConfigSnapshot.

Usage

Create a reloading provider by specifying the snapshot type and file path:

// Using with a JSON snapshot and a custom poll interval
let jsonProvider = try await ReloadingFileProvider<JSONSnapshot>(
    filePath: "/etc/config.json",
    pollInterval: .seconds(30)
)

// Using with a YAML snapshot
let yamlProvider = try await ReloadingFileProvider<YAMLSnapshot>(
    filePath: "/etc/config.yaml"
)

Service integration

This provider implements the Service protocol and must be run within a ServiceGroup to enable automatic reloading:

let provider = try await ReloadingFileProvider<JSONSnapshot>(filePath: "/etc/config.json")
let serviceGroup = ServiceGroup(services: [provider], logger: logger)
try await serviceGroup.run()

The provider monitors the file by polling at the specified interval (default: 15 seconds) and notifies any active watchers when it detects changes.

On platforms with Unix signals, a running provider also checks the file whenever the process receives SIGHUP, so you don’t have to wait for the next poll. Either way, the file is only reloaded if its modification timestamp or resolved path changed.

Configuration from a reader

You can also initialize the provider using a configuration reader:

let envConfig = ConfigReader(provider: EnvironmentVariablesProvider())
let provider = try await ReloadingFileProvider<JSONSnapshot>(config: envConfig)

This expects configuration keys that specify the file path and optionally other format-specific values. For a full list of configuration keys, see init(snapshotType:parsingOptions:config:logger:metrics:).

File monitoring

The provider detects changes by monitoring both file timestamps and symlink target changes. When it detects a change, it reloads the file and notifies all active watchers of the updated configuration values.