@microsoft/refreshing-config

refreshing-config

Configuration library that can dynamically refresh configuration values.

Usage

1. Construct your configuration store
2. Instantiate an instance of RefreshingConfig passing your store to the constructor
3. Optionally, instantiate your refresh policies and/or change notifiers and add them by calling withExtension(extension: object)
4. Call get(name: string) or getAll() to retrieve configuration values
5. Call set(name: string, value: any) or delete(name: string) to manipulate configuration values

It is important to note that the configuration values are manipulated in place when they are refreshed so if you have an instance of an object returned from get or getAll it may be modified whenever a refresh occurs (this is intentional), if you don't want the values to change you should clone the object and use the clone.

Stores

refreshing-config requires a store that will store the configuration values. We provide a Redis-backed store in https://npmjs.org/package/refreshing-config-redis but you can implement your own store for your configuration backend.

Writing a store

Stores must implement getAll(): IPromise<object> and can optionally implement set(name: string, value: any): IPromise<any> and delete(name: string): IPromise<void>. The getAll() function should return an object whose keys are the names of the configuration values and the value is the configuration value itself. Stores should support the full set of JavaScript data types.

Events

The following events are emitted from RefreshingConfig:

• set(name, value): Emitted when a configuration value has been set in the underlying store where name is the name of the configuration value and value is the new value.
• delete(name): Emitted when a configuration value has been deleted where name is the name of the configuration value that was deleted.
• changed(config, patch): Emitted when a change is detected in the configuration values after a refresh where config is the updated configuration (including unchanged values) and patch is a JSON patch describing the changes that were detected.
• refresh(config): Emitted whenever the configuration is refreshed from the store where config is the configuration after the refresh.

The object returned from getAll() also has the RefreshingConfig instance itself in the _config property. This is useful if you want to pass the configuration object around your application and allowing it to subscribe to updates or otherwise manage the configuration.

Extensions

You can extend refreshing-config's behavior by attaching extensions using withExtension:

const config = new RefreshingConfig.RefreshingConfig(store)
  .withExtension(myExtension1)
  .withExtension(myExtension2);

Refresh policies

Refresh policies define when refreshing-config should go back to the store to get updated configuration values. Refresh policies can either be reactive (refreshing-config asks them if it should go back to the store) or proactive (they notify refreshing-config that it needs to refresh). If there are multiple refresh policies attached then refreshing-config will go back to the store if any of them say a refresh is required.

Refresh policies are bypassed in the following scenarios:

• The read of the first configuration value (to get the initial set of configuration values)
• After a set or delete (because we know the configuration values are stale)

If you do not have a refresh policy in place you can explicitly call refresh() to force a refresh.

NeverRefreshPolicy (reactive)

This is the default policy and will only go to the store when the first setting is read or when we know the values have changed (for example, if set or delete is called).

const config = new RefreshingConfig.RefreshingConfig(store)
  .withExtension(new RefreshingConfig.RefreshPolicy.NeverRefreshPolicy());

AlwaysRefreshPolicy (reactive)

This policy will go back to the store everytime a configuration value is read.

const config = new RefreshingConfig.RefreshingConfig(store)
  .withExtension(new RefreshingConfig.RefreshPolicy.AlwaysRefreshPolicy());

StaleRefreshPolicy (reactive)

This policy will go back to the store if it hasn't been back to the store for the specified number of milliseconds. In this example the store will be accessed at most every 30 seconds:

const config = new RefreshingConfig.RefreshingConfig(store)
  .withExtension(new RefreshingConfig.RefreshPolicy.StaleRefreshPolicy(30000));

IntervalRefreshPolicy (proactive)

This policy will proactively refresh the configuration values from the store at the defined interval. In this example the configuration values will be refreshed every 30 seconds.

const config = new RefreshingConfig.RefreshingConfig(store)
  .withExtension(new RefreshingConfig.RefreshPolicy.IntervalRefreshPolicy(30000));

Writing a refresh policy

A refresh policy must implement either shouldRefresh(): boolean (for reactive refresh policies) or subscribe(subscriber: RefreshingConfig) (for proactive refresh policies). Proactive refresh policies should call subscriber.refresh() whenever they want the configuration values refreshed from the store.

Change notifiers

Change notifiers are notified when refreshing-config has modified a configuration value (for example, when set or delete is called). This can be used to notify others about the need to refresh config. Note that these are not called when configuration values are changed externally in the store, if you want to know about those you should subscribe to the changed event on RefreshingConfig.

Change notifiers are generally paired with a refresh policy, in this pattern the change notifier is told about the change and communicates it to interested consumers, these consumers consume the notification in their refresh policy which then tells the configuration library to retrieve the new values from the store.

There are no out of the box change notifiers but see https://github.com/Microsoft/refreshing-config-redis to see an example refresh policy/change notifier that use Redis pub/sub to refresh configuration values automatically when they change.

Writing a change notifier

A change notifier must implement the publish(operation: string, name: string, value: string) method which will be called whenever a set or delete is performed. The operation will either be set or delete, the name will be the name of the configuration value impacted, and the value will be the new value (for set operations).

Contributing

Pull requests will gladly be considered!

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [e-mail] with any additional questions or comments.