Support dynamic refresh

examples/README.md

@@ -39,7 +39,7 @@ To run the examples using the published version of the package:
         ```bash
         npx cross-env APPCONFIG_CONNECTION_STRING="<appconfig connection string>" 
         ```
-    
+
 3. Run the examples:
     ```bash
     node helloworld.mjs

examples/refresh.mjs

@@ -0,0 +1,44 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import * as dotenv from "dotenv";
+import { promisify } from "util";
+dotenv.config();
+const sleepInMs = promisify(setTimeout);
+
+/**
+ * This example retrives all settings with key following pattern "app.settings.*", i.e. starting with "app.settings.".
+ * With the option `trimKeyPrefixes`, it trims the prefix "app.settings." from keys for simplicity.
+ * Value of config "app.settings.message" will be printed.
+ * It also watches for changes to the key "app.settings.sentinel" and refreshes the configuration when it changes.
+ *
+ * Below environment variables are required for this example:
+ * - APPCONFIG_CONNECTION_STRING
+ */
+
+import { load } from "@azure/app-configuration-provider";
+const connectionString = process.env.APPCONFIG_CONNECTION_STRING;
+const settings = await load(connectionString, {
+    selectors: [{
+        keyFilter: "app.settings.*"
+    }],
+    trimKeyPrefixes: ["app.settings."],
+    refreshOptions: {
+        watchedSettings: [{ key: "app.settings.sentinel" }],
+        refreshIntervalInMs: 10 * 1000 // Default value is 30 seconds, shorted for this sample
+    }
+});
+
+console.log("Using Azure portal or CLI, update the `app.settings.message` value, and then update the `app.settings.sentinel` value in your App Configuration store.")
+
+// eslint-disable-next-line no-constant-condition
+while (true) {
+    // Refreshing the configuration setting
+    await settings.refresh();
+
+    // Current value of message
+    console.log(settings.get("message"));
+
+    // Waiting before the next refresh
+    await sleepInMs(5000);
+}

src/AzureAppConfiguration.ts

@@ -1,6 +1,19 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
+import { Disposable } from "./common/disposable";
+
 export type AzureAppConfiguration = {
-    // methods for advanced features, e.g. refresh()
+    /**
+     * API to trigger refresh operation.
+     */
+    refresh(): Promise<void>;
+
+    /**
+     * API to register callback listeners, which will be called only when a refresh operation successfully updates key-values.
+     *
+     * @param listener - Callback funtion to be registered.
+     * @param thisArg - Optional. Value to use as `this` when executing callback.
+     */
+    onRefresh(listener: () => any, thisArg?: any): Disposable;
 } & ReadonlyMap<string, any>;

src/AzureAppConfigurationImpl.ts

@@ -1,29 +1,37 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
-import { AppConfigurationClient, ConfigurationSetting, ListConfigurationSettingsOptions } from "@azure/app-configuration";
+import { AppConfigurationClient, ConfigurationSetting, ConfigurationSettingId, GetConfigurationSettingResponse, ListConfigurationSettingsOptions } from "@azure/app-configuration";
+import { RestError } from "@azure/core-rest-pipeline";
 import { AzureAppConfiguration } from "./AzureAppConfiguration";
 import { AzureAppConfigurationOptions } from "./AzureAppConfigurationOptions";
 import { IKeyValueAdapter } from "./IKeyValueAdapter";
 import { JsonKeyValueAdapter } from "./JsonKeyValueAdapter";
-import { KeyFilter, LabelFilter } from "./types";
+import { DefaultRefreshIntervalInMs, MinimumRefreshIntervalInMs } from "./RefreshOptions";
+import { Disposable } from "./common/disposable";
 import { AzureKeyVaultKeyValueAdapter } from "./keyvault/AzureKeyVaultKeyValueAdapter";
-import { CorrelationContextHeaderName } from "./requestTracing/constants";
+import { RefreshTimer } from "./refresh/RefreshTimer";
+import { CorrelationContextHeaderName, RequestType } from "./requestTracing/constants";
 import { createCorrelationContextHeader, requestTracingEnabled } from "./requestTracing/utils";
-import { SettingSelector } from "./types";
+import { KeyFilter, LabelFilter, SettingSelector } from "./types";
 
-export class AzureAppConfigurationImpl extends Map<string, unknown> implements AzureAppConfiguration {
+export class AzureAppConfigurationImpl extends Map<string, any> implements AzureAppConfiguration {
     #adapters: IKeyValueAdapter[] = [];
     /**
      * Trim key prefixes sorted in descending order.
      * Since multiple prefixes could start with the same characters, we need to trim the longest prefix first.
      */
     #sortedTrimKeyPrefixes: string[] | undefined;
     readonly #requestTracingEnabled: boolean;
-    #correlationContextHeader: string | undefined;
     #client: AppConfigurationClient;
     #options: AzureAppConfigurationOptions | undefined;
 
+    // Refresh
+    #refreshInterval: number = DefaultRefreshIntervalInMs;
+    #onRefreshListeners: Array<() => any> = [];
+    #sentinels: ConfigurationSettingId[];
+    #refreshTimer: RefreshTimer;
+
     constructor(
         client: AppConfigurationClient,
         options: AzureAppConfigurationOptions | undefined
@@ -34,20 +42,53 @@ export class AzureAppConfigurationImpl extends Map<string, unknown> implements A
 
         // Enable request tracing if not opt-out
         this.#requestTracingEnabled = requestTracingEnabled();
-        if (this.#requestTracingEnabled) {
-            this.#enableRequestTracing();
-        }
 
         if (options?.trimKeyPrefixes) {
             this.#sortedTrimKeyPrefixes = [...options.trimKeyPrefixes].sort((a, b) => b.localeCompare(a));
         }
+
+        if (options?.refreshOptions?.enabled) {
+            const { watchedSettings, refreshIntervalInMs } = options.refreshOptions;
+            // validate watched settings
+            if (watchedSettings === undefined || watchedSettings.length === 0) {
+                throw new Error("Refresh is enabled but no watched settings are specified.");
+            }
+
+            // custom refresh interval
+            if (refreshIntervalInMs !== undefined) {
+                if (refreshIntervalInMs < MinimumRefreshIntervalInMs) {
+                    throw new Error(`The refresh interval cannot be less than ${MinimumRefreshIntervalInMs} milliseconds.`);
+
+                } else {
+                    this.#refreshInterval = refreshIntervalInMs;
+                }
+            }
+
+            this.#sentinels = watchedSettings.map(setting => {
+                if (setting.key.includes("*") || setting.key.includes(",")) {
+                    throw new Error("The characters '*' and ',' are not supported in key of watched settings.");
+                }
+                if (setting.label?.includes("*") || setting.label?.includes(",")) {
+                    throw new Error("The characters '*' and ',' are not supported in label of watched settings.");
+                }
+                return { ...setting };
+            });
+
+            this.#refreshTimer = new RefreshTimer(this.#refreshInterval);
+        }
+
         // TODO: should add more adapters to process different type of values
         // feature flag, others
         this.#adapters.push(new AzureKeyVaultKeyValueAdapter(options?.keyVaultOptions));
         this.#adapters.push(new JsonKeyValueAdapter());
     }
 
-    async load() {
+
+    get #refreshEnabled(): boolean {
+        return !!this.#options?.refreshOptions?.enabled;
+    }
+
+    async load(requestType: RequestType = RequestType.Startup) {
         const keyValues: [key: string, value: unknown][] = [];
 
         // validate selectors
@@ -60,25 +101,111 @@ export class AzureAppConfigurationImpl extends Map<string, unknown> implements A
             };
             if (this.#requestTracingEnabled) {
                 listOptions.requestOptions = {
-                    customHeaders: this.#customHeaders()
+                    customHeaders: this.#customHeaders(requestType)
                 }
             }
 
             const settings = this.#client.listConfigurationSettings(listOptions);
 
             for await (const setting of settings) {
                 if (setting.key) {
-                    const [key, value] = await this.#processAdapters(setting);
-                    const trimmedKey = this.#keyWithPrefixesTrimmed(key);
-                    keyValues.push([trimmedKey, value]);
+                    const keyValuePair = await this.#processKeyValues(setting);
+                    keyValues.push(keyValuePair);
+                }
+                // update etag of sentinels if refresh is enabled
+                if (this.#refreshEnabled) {
+                    const matchedSentinel = this.#sentinels.find(s => s.key === setting.key && s.label === setting.label);
+                    if (matchedSentinel) {
+                        matchedSentinel.etag = setting.etag;
+                    }
                 }
             }
         }
+        this.clear(); // clear existing key-values in case of configuration setting deletion
         for (const [k, v] of keyValues) {
             this.set(k, v);
         }
     }
 
+    /**
+     * Refresh the configuration store.
+     */
+    public async refresh(): Promise<void> {
+        if (!this.#refreshEnabled) {
+            return Promise.resolve();
+        }
+
+        // if still within refresh interval/backoff, return
+        if (!this.#refreshTimer.canRefresh()) {
+            return Promise.resolve();
+        }
+
+        // try refresh if any of watched settings is changed.
+        let needRefresh = false;
+        for (const sentinel of this.#sentinels) {
+            let response: GetConfigurationSettingResponse | undefined;
+            try {
+                response = await this.#client.getConfigurationSetting(sentinel, {
+                    onlyIfChanged: true,
+                    requestOptions: {
+                        customHeaders: this.#customHeaders(RequestType.Watch)
+                    }
+                });
+            } catch (error) {
+                if (error instanceof RestError && error.statusCode === 404) {
+                    response = undefined;
+                } else {
+                    throw error;
+                }
+            }
+
+            if (response === undefined || response.statusCode === 200) {
+                // sentinel deleted / changed.
+                sentinel.etag = response?.etag;// update etag of the sentinel
+                needRefresh = true;
+                break;
+            }
+        }
+        if (needRefresh) {
+            try {
+                await this.load(RequestType.Watch);
+                this.#refreshTimer.reset();
+            } catch (error) {
+                // if refresh failed, backoff
+                this.#refreshTimer.backoff();
+                throw error;
+            }
+
+            // successfully refreshed, run callbacks in async
+            for (const listener of this.#onRefreshListeners) {
+                listener();
+            }
+        }
+    }
+
+    onRefresh(listener: () => any, thisArg?: any): Disposable {
+        if (!this.#refreshEnabled) {
+            throw new Error("Refresh is not enabled.");
+        }
+
+        const boundedListener = listener.bind(thisArg);
+        this.#onRefreshListeners.push(boundedListener);
+
+        const remove = () => {
+            const index = this.#onRefreshListeners.indexOf(boundedListener);
+            if (index >= 0) {
+                this.#onRefreshListeners.splice(index, 1);
+            }
+        }
+        return new Disposable(remove);
+    }
+
+    async #processKeyValues(setting: ConfigurationSetting<string>): Promise<[string, unknown]> {
+        const [key, value] = await this.#processAdapters(setting);
+        const trimmedKey = this.#keyWithPrefixesTrimmed(key);
+        return [trimmedKey, value];
+    }
+
     async #processAdapters(setting: ConfigurationSetting<string>): Promise<[string, unknown]> {
         for (const adapter of this.#adapters) {
             if (adapter.canProcess(setting)) {
@@ -99,17 +226,13 @@ export class AzureAppConfigurationImpl extends Map<string, unknown> implements A
         return key;
     }
 
-    #enableRequestTracing() {
-        this.#correlationContextHeader = createCorrelationContextHeader(this.#options);
-    }
-
-    #customHeaders() {
+    #customHeaders(requestType: RequestType) {
         if (!this.#requestTracingEnabled) {
             return undefined;
         }
 
         const headers = {};
-        headers[CorrelationContextHeaderName] = this.#correlationContextHeader;
+        headers[CorrelationContextHeaderName] = createCorrelationContextHeader(this.#options, requestType);
         return headers;
     }
 }

src/AzureAppConfigurationOptions.ts

@@ -3,6 +3,7 @@
 
 import { AppConfigurationClientOptions } from "@azure/app-configuration";
 import { AzureAppConfigurationKeyVaultOptions } from "./keyvault/AzureAppConfigurationKeyVaultOptions";
+import { RefreshOptions } from "./RefreshOptions";
 import { SettingSelector } from "./types";
 
 export const MaxRetries = 2;
@@ -35,4 +36,8 @@ export interface AzureAppConfigurationOptions {
      * Specifies options used to resolve Vey Vault references.
      */
     keyVaultOptions?: AzureAppConfigurationKeyVaultOptions;
+    /**
+     * Specifies options for dynamic refresh key-values.
+     */
+    refreshOptions?: RefreshOptions;
 }

src/RefreshOptions.ts

@@ -0,0 +1,27 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { WatchedSetting } from "./WatchedSetting";
+
+export const DefaultRefreshIntervalInMs = 30 * 1000;
+export const MinimumRefreshIntervalInMs = 1 * 1000;
+
+export interface RefreshOptions {
+    /**
+     * Specifies whether the provider should automatically refresh when the configuration is changed.
+     */
+    enabled: boolean;
+
+    /**
+     * Specifies the minimum time that must elapse before checking the server for any new changes.
+     * Default value is 30 seconds. Must be greater than 1 second.
+     * Any refresh operation triggered will not update the value for a key until after the interval.
+     */
+    refreshIntervalInMs?: number;
+
+    /**
+     * One or more configuration settings to be watched for changes on the server. 
+     * Any modifications to watched settings will refresh all settings loaded by the configuration provider.
+     */
+    watchedSettings?: WatchedSetting[];
+}

src/WatchedSetting.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+/**
+ * Fields that uniquely identify a watched configuration setting.
+ */
+export interface WatchedSetting {
+    /**
+     * The key for this setting.
+     */
+    key: string;
+
+    /**
+     * The label for this setting.
+     * Leaving this undefined means this setting does not have a label.
+     */
+    label?: string;
+}

src/common/disposable.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+export class Disposable {
+    private disposed = false;
+    constructor(private callOnDispose: () => any) { }
+
+    dispose() {
+        if (!this.disposed) {
+            this.callOnDispose();
+        }
+        this.disposed = true;
+    }
+
+}